简中 ▾

◆ API 参考

Seeknetic API 文档

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

认证 X-API-Key

格式 application/json

API 区域端点

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

认证

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

使用 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 向量(同步处理)。

请求 curl

鉴权

X-API-Key

Content-Type

application/json

请求体

{"video_url":"https://..."}

bash

curl -X POST "https://api.jp.seeknetic.com/video_embedding/encode_video" \
  -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 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。

请求 curl

鉴权

X-API-Key

Content-Type

application/json

请求体

{"text":"..."}

bash

curl -X POST "https://api.jp.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.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 提取。

请求 curl

鉴权

X-API-Key

Content-Type

application/json

请求体

{"video_url":"https://..."}

bash

curl -X POST "https://api.jp.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.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}

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

请求 curl

鉴权

X-API-Key

路径参数

request_id

状态流转:

pending

→

processing

→

completed

bash

curl -X GET "https://api.jp.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.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 编码的视频数据。

请求 curl

鉴权

X-API-Key

Content-Type

application/json

请求体

{"video_url":"https://..."}

bash

curl -X POST "https://api.jp.seeknetic.com/video_tagging" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://example.com/video.mp4"}'

示例 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

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

请求 curl

鉴权

X-API-Key

Content-Type

application/json

请求体

{"video_url":"https://..."}

bash

curl -X POST "https://api.jp.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.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

创建新的视频集合。

请求 curl

鉴权

X-API-Key

Content-Type

application/json

请求体

{"name":"...","description":"..."}

bash

curl -X POST "https://api.jp.seeknetic.com/collections" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Video Collection","description":"Test collection"}'

示例 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

列出所有视频集合。

请求 curl

鉴权

X-API-Key

bash

curl -X GET "https://api.jp.seeknetic.com/collections" \
  -H "X-API-Key: {your_api_key}"

示例 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

在集合中搜索相似的视频片段(基于语义向量搜索)。

请求 curl

鉴权

X-API-Key

Content-Type

application/json

路径参数

collection_id

请求体

{"text":"...","top_k":10}

bash

curl -X POST "https://api.jp.seeknetic.com/collections/{collection_id}/search" \
  -H "X-API-Key: {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{"text":"A dog playing in the park","top_k":10}'

示例 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 的文件)。

请求 curl

鉴权

X-API-Key

Content-Type

multipart/form-data

路径参数

collection_id

请求体

file (multipart)

bash

curl -X POST "https://api.jp.seeknetic.com/collections/{collection_id}/videos/upload" \
  -H "X-API-Key: {your_api_key}" \
  -F "file=@video.mp4"

示例 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

轻量级状态查询,用于监控视频处理进度。

请求 curl

鉴权

X-API-Key

路径参数

video_id

bash

curl -X GET "https://api.jp.seeknetic.com/videos/{video_id}/status" \
  -H "X-API-Key: {your_api_key}"

处理阶段:

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