API v1 · AVAILABLE

API 接入文档

通过标准 HTTP 接口将视频去字幕能力接入你的业务。提供可下载的公网 HTTPS 文件地址即可创建任务。

创建 API Key

认证方式Bearer API Key

文件来源HTTPS URL

接口格式JSON

AUTHENTICATION

认证

HEADER

在 API 接入页面创建 API Key，并通过每次请求的 Authorization Header 发送。API Key 只应保存在服务端。

Authorization Header

Authorization: Bearer wj_live_xxx

使用可持续访问的文件地址source_url 必须是公网 HTTPS 地址，并在任务开始下载前保持有效；带时效签名的云存储链接应预留足够有效期。

PRODUCT DIRECTORY

视频去字幕

AVAILABLE

提供可直接下载的公网 HTTPS 视频地址即可创建任务，不需要提交视频时长。修复区域和保护区域可选，任务成功后查询响应会返回最终视频下载地址。

PRODUCT 01

视频去字幕

subtitles_v1

已开放

创建去字幕任务

POST/api/v1/products/subtitles_v1/tasks

只需提交可直接下载的公网 HTTPS 视频地址；处理区域和保护区域可选，不需要提交视频时长。HTTP 202 表示任务已入队，视频导入、校验与积分预留将在后台完成。

请求头

字段	类型	必填	说明
`Authorization`	string	是	Bearer API Key，例如 Bearer wj_live_xxx。
`Idempotency-Key`	string	推荐	本次业务请求的唯一标识。相同值重复提交时返回原任务，避免网络重试产生重复扣费。
`Content-Type`	string	是	固定为 application/json。

请求参数

字段	类型	必填	说明
`source_url`	string	是	可直接下载视频文件的公网 HTTPS 地址，任务开始处理时必须仍然有效。
`edit_regions`	array	否	指定修复区域；省略或空数组表示全画面。边界向外融合 16 个原视频像素。
`protect_regions`	array	否	保留原视频的保护区域，优先于修复区域和融合带。两类区域合计最多 100 个。
`区域.x / y`	number	是	相对原视频左上角的归一化坐标，范围 0 到 1。
`区域.width / height`	number	是	归一化宽高，必须大于 0 且区域不能超出原画面。
`区域.start_ms / end_ms`	integer	否	原视频时间轴毫秒，区间包含开始、不包含结束；省略表示覆盖全片。

CREATE SUBTITLE TASK

curl -X POST https://ai.seekthex.com/api/v1/products/subtitles_v1/tasks \
  -H "Authorization: Bearer wj_live_xxx" \
  -H "Idempotency-Key: subtitle-20260818-001" \
  -H "Content-Type: application/json" \
  -d '{
    "source_url": "https://storage.example.com/videos/meeting.mp4",
    "edit_regions": [{ "x": 0.2, "y": 0.3, "width": 0.6, "height": 0.4 }],
    "protect_regions": [{ "x": 0.4, "y": 0.5, "width": 0.1, "height": 0.1, "start_ms": 2900, "end_ms": 3300 }]
  }'

成功响应 · HTTP 202 Accepted

字段	类型	说明
`id`	string	任务唯一 ID。后续使用该值查询状态和结果。
`status`	string	当前任务状态。创建成功时为 queued；所有可能值见下方任务状态表。
`progress`	integer	处理进度，范围为 0 到 100。
`duration_ms`	integer	创建时尚未读取视频则为 0，随后查询任务可获得真实时长。
`billable_seconds`	integer	创建时可能为 0，读取视频后更新为实际计费秒数。
`reserved_points`	integer	创建时可能为 0，读取视频后更新为本次任务所需积分。
`created_at`	string	任务创建时间，ISO 8601 格式。

HTTP 202 ACCEPTED

{
  "id": "task_xxx",
  "status": "queued",
  "progress": 0,
  "duration_ms": 0,
  "billable_seconds": 0,
  "reserved_points": 0,
  "created_at": "2026-08-18T02:00:00Z"
}

错误响应

错误统一返回 { "error": { "code": "...", "message": "..." } }。客户端应同时判断 HTTP 状态码和 error.code。

HTTP	错误码	可重试	说明
400	`invalid_json`	否	请求体不是有效 JSON、包含未知字段或字段类型错误。
400	`invalid_source`	修正后	source_url 缺失、不是公网 HTTPS 地址或指向受限网络。
400	`invalid_media`	修正后	source_url 无法下载、不是受支持的视频或视频时长超过限制。
400	`invalid_regions`	修正后	归一化区域坐标或时间范围不符合要求。
409	`idempotency_conflict`	修正后	同一个幂等键已用于不同的视频或区域参数。
400	`invalid_product`	否	该处理能力不存在或暂未开放。
401	`missing_api_key`	修正后	未携带 Authorization Bearer API Key。
401	`invalid_api_key`	修正后	API Key 无效或已撤销。
402	`insufficient_points`	充值后	可用积分不足，任务未创建。
500	`internal_error`	是	服务暂时无法完成请求。使用相同 Idempotency-Key 重试。

查询任务与结果

GET/api/v1/tasks/{task_id}

使用创建响应中的任务 ID 查询。HTTP 200 仅代表查询成功，任务是否完成必须以响应中的 status 为准。

路径参数

字段	类型	必填	说明
`task_id`	string	是	创建任务接口返回的任务 ID。

任务状态

status	是否终态	说明	客户端处理
`queued`	否	任务已创建，正在等待处理。	继续查询。
`processing`	否	视频正在处理中，progress 会随处理进度更新。	继续查询。
`succeeded`	是	处理成功，积分已结算。	读取可用的结果字段并及时下载。
`failed`	是	处理失败，预留积分已退回。	读取 error_code 和 error_message，不再轮询。
`cancelled`	是	任务已取消，预留积分已退回。	读取 error_code 和 error_message，不再轮询。

成功响应 · HTTP 200 OK

字段	类型	说明
`id`	string	任务唯一 ID。
`status`	string	当前任务状态。状态含义和客户端处理方式见下方任务状态表。
`progress`	integer	处理进度，范围为 0 到 100。终态时成功为 100，失败或取消可能为 0。
`duration_ms`	integer	输入视频时长，单位为毫秒。
`billable_seconds`	integer	本次任务的计费秒数。
`reserved_points`	integer	任务处理期间冻结的积分。
`settled_points`	integer	任务成功后实际扣除的积分；未成功时为 0。
`output_ready`	boolean	是否至少有一个仍在有效期内的结果可供下载。
`high_quality_result`	object	高清版结果。尚未生成、生成失败或文件已过期时不返回。
`error_code`	string	任务为 failed 或 cancelled 时返回的业务错误码。
`error_message`	string	任务为 failed 或 cancelled 时返回的可展示错误说明。
`created_at`	string	任务创建时间，ISO 8601 格式。
`updated_at`	string	任务最后更新时间，ISO 8601 格式。

结果对象字段

字段	类型	说明
`content_type`	string	结果文件的 MIME 类型，例如 video/mp4。
`size`	integer	结果文件大小，单位为字节。
`duration_ms`	integer	结果视频时长，单位为毫秒；无法读取时不返回。
`download_url`	string	结果文件的临时 HTTPS 下载地址，最长 24 小时有效。
`expires_at`	string	当前下载地址的过期时间。

SUCCEEDED · HTTP 200

{
  "id": "task_xxx",
  "status": "succeeded",
  "progress": 100,
  "duration_ms": 60000,
  "billable_seconds": 60,
  "reserved_points": 300,
  "settled_points": 300,
  "output_ready": true,
  "high_quality_result": {
    "content_type": "video/mp4",
    "size": 18234567,
    "duration_ms": 60000,
    "download_url": "https://media.example.com/high.mp4?t=...&us=...&sign=...",
    "expires_at": "2026-08-21T02:12:00Z"
  },
  "created_at": "2026-08-18T02:00:00Z",
  "updated_at": "2026-08-18T02:12:00Z"
}

FAILED · HTTP 200

{
  "id": "task_xxx",
  "status": "failed",
  "progress": 0,
  "reserved_points": 300,
  "settled_points": 0,
  "output_ready": false,
  "error_code": "processing_failed",
  "error_message": "视频处理未能完成，冻结积分已退回",
  "created_at": "2026-08-18T02:00:00Z",
  "updated_at": "2026-08-18T02:03:00Z"
}

任务终态错误码

status	error_code	说明
`failed`	`insufficient_points`	视频真实时长所需积分超过当前余额；充值后可重新创建任务。
`failed`	`processing_failed`	任务未能完成，积分不扣除；可检查输入视频后重新创建任务。
`cancelled`	`task_cancelled`	任务已取消，积分不扣除。

查询接口错误响应

HTTP	错误码	可重试	说明
401	`missing_api_key`	修正后	未携带 Authorization Bearer API Key。
401	`invalid_api_key`	修正后	API Key 无效或已撤销。
404	`not_found`	否	任务不存在，或任务不属于当前 API Key 的工作区。
500	`internal_error`	是	服务暂时无法完成查询，可稍后重试。

及时下载结果请在 expires_at 前完成下载；地址过期后可重新查询任务获取新地址，结果文件到期删除后不可恢复。

取消任务

POST/api/v1/tasks/{task_id}/cancel

使用相同 Bearer API Key 提交取消请求。HTTP 202 表示取消意图已保存，后台会停止尚未完成的分片并确认资源退出。

BALANCE

查询积分余额

GET

GET/api/v1/balance

查询当前可用积分和已预留积分。创建任务时余额不足会返回 HTTP 402。

成功响应 · HTTP 200 OK

字段	类型	说明
`wallet`	object	当前 API Key 所属工作区的钱包信息。
`wallet.workspace_id`	string	工作区唯一 ID。
`wallet.available_points`	integer	当前可用于创建新任务的积分。
`wallet.held_points`	integer	处理中任务已预留、尚未最终结算的积分。

HTTP 200 OK

{
  "wallet": {
    "workspace_id": "workspace_xxx",
    "available_points": 9700,
    "held_points": 300
  }
}

错误响应

HTTP	错误码	说明
401	`missing_api_key` / `invalid_api_key`	API Key 缺失、无效或已撤销。
500	`internal_error`	服务暂时无法读取积分余额，可稍后重试。

登录并创建第一个 API Key

FILE LIFECYCLE

文件保存规则

RESULTS

调用方负责保证 source_url 在任务读取期间可用；平台不会修改或删除调用方提供的文件。任务结果为临时文件，请在查询响应给出的有效期内下载。

ERRORS

错误码

JSON

接口错误统一返回 HTTP 状态码和 JSON 错误对象。客户端应同时判断 HTTP 状态码与 error.code。

Error Response

{
  "error": {
    "code": "invalid_parameters",
    "message": "框选像素坐标无效"
  }
}

HTTP	错误码	说明
400	`invalid_json`	请求体不是有效 JSON，或包含无法解析的字段值。
400	`invalid_source`	`source_url` 缺失或不是可访问的公网 HTTPS 地址。
400	`invalid_media`	地址无法下载或文件不是受支持的视频。
400	`invalid_parameters`	处理模式、像素坐标或其他产品参数不符合要求。
401	`missing_api_key`	请求没有携带 Bearer API Key。
401	`invalid_api_key`	API Key 无效或已撤销。
402	`insufficient_points`	当前可用积分不足以创建任务。
404	`not_found`	任务不存在，或不属于当前工作区。
500	`internal_error`	服务暂时无法完成请求，可稍后重试。