视频描述 API 文档

所有的 API 请求都需要通过 Authorization 头中的 Bearer 令牌进行身份验证。

Authorization: Bearer nxt_your_api_key_here

使用我们的沙盒环境免费测试您的 webhook 集成。沙盒任务模拟完整的工作流而无需实际进行视频处理。

沙盒的优势

• 免费的每日配额 - 无需代币
• 具备 HMAC 签名的真实 Webhook 推送
• 不需要提供真实的视频 URL
• 支持重放 Webhook 以进行调试

POST /v1/sandbox/video-descriptions

{
  "frames": 10,
  "webhook": {
    "url": "https://your-app.com/webhooks/video"
  },
  "client_context": {
    "lang": "en",
    "output_fields": ["title", "description", "tags"],
    "custom_instructions": "Focus on technical details"
  }
}

上线前使用演示 API 结合真实的异步工作流和 webhook 交付进行集成。用来验证您的视频直连 URL 和 webhook 接收器。

端点

• POST /api/demo/v1/video-descriptions — 创建演示任务（仅直连 URL）
• GET /api/demo/v1/video-descriptions/{job_id} — 获取状态/结果
• POST /api/demo/v1/video-descriptions/{job_id}/replay-webhook — 重新发送 webhook 到您的接收器
• GET /api/demo/v1/webhook-secret — 获取用于签名验证的 webhook 密钥

创建演示任务（示例）

curl -X POST https://your-portal.com/api/demo/v1/video-descriptions \
  -H "X-API-Key: demo_your_demo_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "type": "direct_url",
      "url": "https://example.com/video.mp4"
    },
    "frames": 10,
    "webhook": {
      "url": "https://your-app.com/webhooks/demo"
    },
    "client_context": {
      "lang": "en",
      "output_fields": ["title", "description", "tags"],
      "custom_instructions": "Make the description more detailed"
    }
  }'

Webhook 签名

演示 API 使用与主 API 相同的签名头向您的 URL 转发 webhooks：X-Nxt-Timestamp 和 X-Nxt-Signature。使用 GET /api/demo/v1/webhook-secret 来检索用于验证的密钥。

请求体

响应

返回 202 Accepted 以及任务 ID。

{
  "job_id": "01HXYZ123ABC",
  "status": "queued"
}

轮询任务状态。当 webhooks 不方便时，可用于监控处理进度。

任务状态

所有 webhook 都使用 HMAC-SHA256 进行签名。验证签名可以确保真实性。

签名标头

X-Nxt-Timestamp: 1707400000
X-Nxt-Signature: sha256=abc123def456...

验证示例（Python）

import hmac
import hashlib

def verify_webhook(raw_body: bytes, timestamp: str, signature_header: str, secret: str) -> bool:
    # Signature header format: "sha256="
    expected_sig = signature_header.removeprefix("sha256=")
    message = raw_body + timestamp.encode()
    computed = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(computed, expected_sig)

对于私人视频，请使用来源提供者 (Source Provider) 模式。当我们的 API 需要获取视频时，您的端点将作为访问代理，返回预签名 URL。

工作流

1. 1 您在任务提交时附带 source.provider 配置
2. 2 我们的 API 使用带签名的请求调用您的端点
3. 3 您验证签名并返回预签名的 URL
4. 4 我们的 API 根据预签名 URL 提取视频

API 返回标准 HTTP 状态码及详细错误信息。

每个成功任务的基础消耗是 1 代币。音频转录是一项附加服务，每采集10秒的音频片段计费一次。最后费用将在 webhook billing.token_cost 字段进行汇报。