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 错误