S
Seeknetic
简中 ▾
English 简体中文 繁體中文
注册
◆ API 参考

Seeknetic API 文档

使用 Seeknetic 云端 API 生成 embeddings 与 tags、管理集合，并完成语义检索工作流。

认证 X-API-Key
格式 application/json
控制台 accounts.seeknetic.com

For production integration, we strongly recommend using the official SDKs first, then fallback to direct HTTP APIs when needed.

API 区域端点

区域 基础 URL 状态
日本东京 https://api.seeknetic.com 可用
美国俄勒冈州 https://api.us.seeknetic.com 即将推出
中国北京 https://api.cn.seeknetic.com 即将推出

认证

所有模型服务端点都需要 API 密钥认证。

使用 API 密钥

你可以通过以下两种方式提供 API 密钥：

方式 1:X-API-Key 头(推荐)

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

方式 2:Authorization 头

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

File Upload

/files/upload/tensors is a standalone upload API. It is not part of embedding or tagging endpoints.

POST /files/upload/tensors

Upload preprocessed tensor JSON (embedding/tagging) and get r2_keys for later async API calls.

请求 curl
鉴权
X-API-Key or Authorization: Bearer
Content-Type
application/json
请求体
{"service","video_input/audio_input/video_kwargs","request_id"}
bash
curl -X POST "https://api.seeknetic.com/files/upload/tensors" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "service":"embedding",
    "request_id":"emb-task-0001",
    "video_input":{"data":"AAAB...","shape":[1,12,3,224,224],"dtype":"uint8"},
    "audio_input":{"data":"AAAB...","shape":[1,1,220500],"dtype":"float32"}
  }'
示例 python
python
import requests

response = requests.post(
    "https://api.seeknetic.com/files/upload/tensors",
    headers={
        "X-API-Key": "{your_api_key}",
        "Content-Type": "application/json"
    },
    json={
        "service": "embedding",
        "request_id": "emb-task-0001",
        "video_input": {
            "data": "AAAB...",
            "shape": [1, 12, 3, 224, 224],
            "dtype": "uint8"
        },
        "audio_input": {
            "data": "AAAB...",
            "shape": [1, 1, 220500],
            "dtype": "float32"
        }
    }
)

print(response.json())

视频 Embedding

将视频或文本编码为向量表示，用于语义搜索和相似度计算。

If you use tensor mode here, first upload tensor payloads via /files/upload/tensors.

POST /video_embedding/encode_text

将文本编码为 embedding 向量，用于语义搜索。

使用此端点创建可与视频 embedding 比较的查询 embedding。

请求 curl
鉴权
X-API-Key
Content-Type
application/json
请求体
{"text":"..."}
bash
curl -X POST "https://api.seeknetic.com/video_embedding/encode_text" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"text":"A dog playing in the park"}'
示例 python
python
import requests

response = requests.post(
    "https://api.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 提取。

Also supports tensor mode: tensor.video_input_key / tensor.audio_input_key (from /files/upload/tensors).

请求 curl
鉴权
X-API-Key
Content-Type
application/json
请求体
{"video_url":"https://..."}
bash
curl -X POST "https://api.seeknetic.com/video_embedding/encode_video/async" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://example.com/video.mp4"}'
示例 python
python
import requests
import time

# 1. Submit async task
response = requests.post(
    "https://api.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.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}

查询异步任务的状态和结果。

请求 curl
鉴权
X-API-Key
路径参数
request_id
状态流转:
pending
→
processing
→
completed
bash
curl -X GET "https://api.seeknetic.com/async_status/{request_id}" \
  -H "X-API-Key: {your_api_key}"
示例 python
python
import requests

request_id = "your_request_id_from_async_call"

response = requests.get(
    f"https://api.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/async

提交视频进行异步标签提取。

Also supports tensor mode: tensor.video_input_key / tensor.video_kwargs_key (from /files/upload/tensors).

请求 curl
鉴权
X-API-Key
Content-Type
application/json
请求体
{"video_url":"https://..."}
bash
curl -X POST "https://api.seeknetic.com/video_tagging/async" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://example.com/video.mp4"}'
示例 python
python
import requests

# Submit async tagging task
response = requests.post(
    "https://api.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}")
GET /async_status/{request_id}

Check tagging async task status by request ID. Returns the same status schema as embedding async status.

请求 curl
鉴权
X-API-Key
路径参数
request_id
bash
curl -X GET "https://api.seeknetic.com/async_status/{request_id}" \
  -H "X-API-Key: {your_api_key}"
示例 python
python
import requests

request_id = "your_request_id_from_async_call"

response = requests.get(
    f"https://api.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']}")

错误处理

常见错误码

状态码 说明 解决方法
400 请求参数错误 检查请求 JSON 格式和必需字段
401 API 密钥无效 检查 API 密钥是否正确
402 Quota exceeded Check usage and billing status, then retry with available quota.
413 Payload too large Reduce request size or upload tensors in smaller chunks.
422 Validation error Verify required fields and schema format based on OpenAPI request model.
429 超过速率限制 降低请求频率或升级计划
500 服务器内部错误 联系技术支持
502 外部 API 错误 外部服务暂时不可用,稍后重试
504 请求超时 尝试使用异步接口或更小的视频

速率限制

  • 每个 API 密钥都有独立的速率限制(QPS - 每秒查询数)
  • 速率限制在创建 API 密钥时设置
  • 超出限制将返回 429 错误