Seeknetic API 文檔

API 區域端點

區域	基礎 URL	狀態
日本東京	`https://api.jp.seeknetic.com`	可用
美國俄勒岡州	`https://api.us.seeknetic.com`	即將推出
中國北京	`https://api.cn.seeknetic.com`	即將推出

🔐 認證

所有模型服務端點都需要 API 密鑰認證。

使用 API 密鑰

方式 1:X-API-Key 頭(推薦)

curl https://api.jp.seeknetic.com/video_tagging \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json"

方式 2:Authorization 頭

curl https://api.jp.seeknetic.com/video_tagging \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json"

🎬 視頻 Embedding

將視頻或文本編碼為向量表示，用於語義搜索和相似度計算。

POST /video_embedding/encode_video

將視頻編碼為 embedding 向量(同步處理)。

Python 示例:

python

import requests
import base64

# Using video URL
response = requests.post(
    "https://api.jp.seeknetic.com/video_embedding/encode_video",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={"video_url": "https://example.com/video.mp4"}
)

result = response.json()
print(f"Embedding dimension: {len(result['embeddings'][0])}")

POST /video_embedding/encode_text

將文本編碼為 embedding 向量，用於語義搜索。

使用此端點創建可與視頻 embedding 比較的查詢 embedding。

Python 示例:

python

import requests

response = requests.post(
    "https://api.jp.seeknetic.com/video_embedding/encode_text",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={"text": "A dog playing in the park"}
)

result = response.json()
print(f"Text embedding dimension: {len(result['embedding'])}")

POST /video_embedding/encode_video/async

提交視頻進行異步 embedding 提取。

Python 示例:

python

import requests
import time

# 1. Submit async task
response = requests.post(
    "https://api.jp.seeknetic.com/video_embedding/encode_video/async",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={"video_url": "https://example.com/video.mp4"}
)

request_id = response.json()["request_id"]
print(f"Task submitted, Request ID: {request_id}")

# 2. Poll status until completion
while True:
    status_response = requests.get(
        f"https://api.jp.seeknetic.com/async_status/{request_id}",
        headers={"X-API-Key": "{your_api_key}"}
    )

    status_data = status_response.json()
    status = status_data['status']

    if status == 'completed':
        embedding = status_data['embedding']
        print(f"Complete! Dimension: {len(embedding)}")
        break
    elif status == 'failed':
        print(f"Failed: {status_data['error_message']}")
        break

    time.sleep(2)

GET /async_status/request_id

查詢異步任務的狀態和結果。

狀態流轉:

pending

→

processing

→

completed

Python 示例:

python

import requests

request_id = "your_request_id_from_async_call"

response = requests.get(
    f"https://api.jp.seeknetic.com/async_status/{request_id}",
    headers={"X-API-Key": "{your_api_key}"}
)

status_data = response.json()
print(f"Status: {status_data['status']}")

if status_data['status'] == 'completed':
    print(f"Result: {status_data['embedding']}")

🏷️ 視頻 Tagging

分析視頻的鏡頭大小、攝像機運動、拍攝角度等元數據信息。

POST /video_tagging

分析視頻並提取元數據(同步處理)。

支持視頻 URL 和 Base64 編碼的視頻數據。

Python 示例:

python

import requests

response = requests.post(
    "https://api.jp.seeknetic.com/video_tagging",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={"video_url": "https://example.com/video.mp4"}
)

result = response.json()
print(f"Tags: {result['tags']}")

POST /video_tagging/async

提交視頻進行異步標簽提取。

Python 示例:

python

import requests

# Submit async tagging task
response = requests.post(
    "https://api.jp.seeknetic.com/video_tagging/async",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={"video_url": "https://example.com/video.mp4"}
)

request_id = response.json()["request_id"]
print(f"Tagging task submitted, Request ID: {request_id}")

📹 視頻管理

視頻管理服務提供視頻集合管理和語義搜索功能。

視頻集合

POST /collections

創建新的視頻集合。

Python 示例:

python

import requests

response = requests.post(
    "https://api.jp.seeknetic.com/collections",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={
        "name": "My Video Collection",
        "description": "Test collection"
    }
)

result = response.json()
print(f"Collection ID: {result['collection_id']}")

GET /collections

列出所有視頻集合。

Python 示例:

python

import requests

response = requests.get(
    "https://api.jp.seeknetic.com/collections",
    headers={"X-API-Key": "{your_api_key}"}
)

collections = response.json()
for collection in collections:
    print(f"Collection: {collection['name']} (ID: {collection['id']})")

POST /collections/collection_id/search

在集合中搜索相似的視頻片段(基於語義向量搜索)。

Python 示例:

python

collection_id = "3d146cd7-4ecb-4dca-bf97-a271a143ee44"

response = requests.post(
    f"https://api.jp.seeknetic.com/collections/{collection_id}/search",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={
        "text": "A dog playing in the park",
        "top_k": 10
    }
)

for result in response.json()['results']:
    print(f"Video: {result['video_id']}, Similarity: {result['similarity']:.2f}")

視頻管理

視頻上傳和處理採用異步處理模式。

POST /collections/collection_id/videos/upload

直接上傳視頻文件(推薦用於 < 100MB 的文件)。

Python 示例:

python

import requests

collection_id = "your_collection_id"

with open("video.mp4", "rb") as video_file:
    files = {"file": video_file}
    response = requests.post(
        f"https://api.jp.seeknetic.com/collections/{collection_id}/videos/upload",
        headers={"X-API-Key": "{your_api_key}"},
        files=files
    )

result = response.json()
print(f"Video uploaded, ID: {result['video_id']}")

GET /videos/video_id/status

輕量級狀態查詢,用於監控視頻處理進度。

處理階段:

uploaded: 已上傳，等待處理
processing: 處理中
processed: 處理完成
failed: 處理失敗

Python 示例:

python

import requests

video_id = "your_video_id"

response = requests.get(
    f"https://api.jp.seeknetic.com/videos/{video_id}/status",
    headers={"X-API-Key": "{your_api_key}"}
)

status_data = response.json()
print(f"Status: {status_data['status']}")
print(f"Progress: {status_data.get('progress', 'N/A')}%")

⚠️ 錯誤處理

常見錯誤碼

狀態碼	說明	解決方法
400	請求參數錯誤	檢查請求 JSON 格式和必需字段
401	API 密鑰無效	檢查 API 密鑰是否正確
404	資源不存在	檢查 URL 路徑和資源 ID
429	超過速率限制	降低請求頻率或升級計劃
500	服務器內部錯誤	聯繫技術支持
502	外部 API 錯誤	外部服務暫時不可用,稍後重試
504	請求超時	嘗試使用異步接口或更小的視頻

速率限制

每個 API 密鑰都有獨立的速率限制(QPS - 每秒查詢數)
速率限制在創建 API 密鑰時設置
超出限制將返回 429 錯誤