codex API 接口文档

面向外部业务后端的异步视频制作接口。提交视频与模板后，轮询任务状态，并从私有腾讯云 COS 获取最终成片。

5 分钟接入路径

客户服务端按下面 5 步接入即可；不要从浏览器、小程序或 App 直接调用本服务。

1. 配置 KAIPAI_BASE_URL=https://kp.baziapi.site 和服务端专用 KAIPAI_API_KEY。
2. 调用 GET /api/v1/templates 获取模板 name，不要在客户端写死模板数量。
3. 用稳定业务单号生成全局唯一 Idempotency-Key。
4. 优先调用 POST /api/v1/jobs/from-url 提交公网视频地址。
5. 保存 job_id，每 3～5 秒轮询 GET /api/v1/jobs/{job_id}；完成后使用 result_url 或结果接口下载成片。

# 1. 健康检查
curl "$KAIPAI_BASE_URL/api/v1/health"

# 2. 获取模板
curl "$KAIPAI_BASE_URL/api/v1/templates" \
  -H "X-API-Key: $KAIPAI_API_KEY"

# 3. 提交任务
curl -X POST "$KAIPAI_BASE_URL/api/v1/jobs/from-url" \
  -H "X-API-Key: $KAIPAI_API_KEY" \
  -H "Idempotency-Key: smart-edit:user123:work456:wsec0008:v1" \
  -H "Content-Type: application/json" \
  -d '{"video_url":"https://media.example.com/work456.mp4","file_name":"work456.mp4","template":"wsec0008","title":"产品介绍","script":"这里是完整口播文案"}'

# 4. 查询任务
curl "$KAIPAI_BASE_URL/api/v1/jobs/$JOB_ID" \
  -H "X-API-Key: $KAIPAI_API_KEY"

# 5. 下载成片，允许 307 跳转
curl -L "$KAIPAI_BASE_URL/api/v1/jobs/$JOB_ID/result" \
  -H "X-API-Key: $KAIPAI_API_KEY" \
  -o result.mp4

鉴权与通用请求头

除健康检查外，所有业务接口都必须由服务端携带 API Key。不要把密钥放入浏览器、小程序、App 或公开仓库。

X-API-Key: <YOUR_API_KEY>
Idempotency-Key: order:20260730:10001

Idempotency-Key 是三个任务提交入口的必填请求头，最大 200 字符，并且在整个服务内全局唯一。相同键会返回首次创建的任务，不会比对第二次提交的文件、模板或文案。

推荐接入流程

1. 调用模板列表，保存需要使用的模板 name。
2. 用稳定业务单号作为幂等键，优先通过 URL 提交异步任务。
3. 保存返回的 job_id，每 3～5 秒查询一次状态。
4. 状态为 completed 后使用 result_url，或调用结果接口获取成片。

支持的视频扩展名：.mp4、.mov、.m4v、.webm。默认最大 500 MiB。

无需鉴权，用于存活检查和版本确认。

{"status":"ok","version":"0.1.73"}

返回当前启用模板。现有目录共 54 套，包括 advanced_red、wsec0002、wsec0003 等；以接口实时返回值为准。预览图统一为 3:4 封面 PNG（720×960），只用于模板卡片展示；成片视频仍保持 9:16。预览图更换后 preview_version 和 preview_url 会变化，列表响应不缓存；接入方应重新拉取列表并使用完整 URL。预览图资源可按版本化 URL 长期缓存，不要删除 v 参数。

curl "$BASE_URL/api/v1/templates" \
  -H "X-API-Key: $KAIPAI_API_KEY"

{
  "items": [{
    "name": "advanced_red",
    "display_name": "高级红·双语",
    "preview_url": "https://kp.baziapi.site/assets/template-previews/advanced_red.png?v=1785542400123456",
    "preview_version": "1785542400123456",
    "duration_ms": 0,
    "ratio_type": 1,
    "health_status": "ready"
  }]
}

推荐入口。服务端下载远程视频后创建异步任务，成功返回 202。

video_url 必须在提交时可由 codex 服务器公网访问；如果是临时签名地址，有效期需要覆盖下载、排队和制作时间，建议至少 30～60 分钟。未在白名单内的素材域名需要提前配置。

每个任务由服务端根据所选模板构建当前素材专属时间线，再提交给开拍上游导出；不复用历史成片。当前生产环境不启用浏览器自动编辑链。导出前会检查背景音乐轨及资源映射；缺失时任务失败，不返回静音降级成片。

curl -X POST "$BASE_URL/api/v1/jobs/from-url" \
  -H "X-API-Key: $KAIPAI_API_KEY" \
  -H "Idempotency-Key: work:10001:advanced_red:v1" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://media.example.com/input.mp4",
    "file_name": "input.mp4",
    "template": "advanced_red",
    "title": "产品介绍",
    "script": "这里是视频实际朗读的完整文案"
  }'

以 multipart/form-data 上传本地视频并创建异步任务，返回 202。

script 可直接传完整口播原稿，无需预先拆段。字幕分段、回退和最终样式宽度自适应规则与 URL 提交接口一致。

curl -X POST "$BASE_URL/api/v1/jobs" \
  -H "X-API-Key: $KAIPAI_API_KEY" \
  -H "Idempotency-Key: upload:10001:advanced_red:v1" \
  -F "video=@./input.mp4;type=video/mp4" \
  -F "template=advanced_red" \
  -F "title=产品介绍" \
  -F "script=这里是完整文案"

智能混剪入口。客户只需要使用 KP 的 X-API-Key，上传 1～5 个 MP4 素材；没有填写文案时走开拍自动写稿，返回数量以开拍实际生成结果为准。

curl -X POST "$BASE_URL/api/v1/auto-mix/jobs" \
  -H "X-API-Key: $KAIPAI_API_KEY" \
  -H "Idempotency-Key: auto-mix:customer-a:work-10001:v1" \
  -F "files=@./clip-1.mp4;type=video/mp4" \
  -F "files=@./clip-2.mp4;type=video/mp4" \
  -F "script_mode=auto" \
  -F "export_resolution=720p"

同一个 job_id 只能由创建它的 API Key 查询、取消或恢复；跨客户访问会返回 404。该接口没有客户任务列表，避免共享开拍账号下的任务互相可见。

上传文件并等待。表单仅支持 video 和 template。任务完成返回 200，等待超时但任务仍运行返回 202，失败或取消返回 409。不推荐新客户使用；小程序、App、网关或长视频场景应使用异步提交 + 轮询。

查询任务状态。COS 成片完成后，每次查询会生成新的短期签名 result_url。

{
  "job_id": "job_0123456789abcdef",
  "status": "publishing",
  "progress": 0,
  "template": "advanced_red",
  "title": "产品介绍",
  "account_alias": "account_01",
  "error": "",
  "created_at": 1785160000.125,
  "updated_at": 1785160060.5,
  "completed_at": null,
  "result_storage": "cos",
  "result_expires_at": null,
  "status_url": "/api/v1/jobs/job_0123456789abcdef",
  "result_url": null
}

COS 模式返回 307 并跳转到短期签名 HTTPS 地址；本地兼容模式返回 200 video/mp4。多数 HTTP 客户端默认会跟随跳转。

curl -L "$BASE_URL/api/v1/jobs/$JOB_ID/result" \
  -H "X-API-Key: $KAIPAI_API_KEY" \
  -o result.mp4

取消与重试

仅 queued 状态可取消，成功返回 200；状态不允许时返回 409。

仅 failed 状态可重试，成功返回 202。如果任务已取得开拍上游结果而只在 COS 回传阶段失败，现有检查点会优先只重试回传，不重新导出。

任务响应字段

任务状态

错误处理

{"detail":"错误说明"}

当前没有稳定的业务错误码。调用方应先按 HTTP 状态码处理，不要长期依赖中文 detail 文案。

Node.js 接入示例

const baseUrl = process.env.KAIPAI_BASE_URL;
const apiKey = process.env.KAIPAI_API_KEY;

const response = await fetch(`${baseUrl}/api/v1/jobs/from-url`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": apiKey,
    "Idempotency-Key": `work:${workId}:advanced_red:v1`,
  },
  body: JSON.stringify({
    video_url: sourceUrl,
    file_name: "input.mp4",
    template: "advanced_red",
    title: "产品介绍",
    script,
  }),
});
if (!response.ok) throw new Error(await response.text());
const job = await response.json();

安全与保留策略

• 业务 API Key 只存放在可信服务端，通过环境变量注入。
• 管理后台可随时查看新生成或已重置的 API Key；服务端使用部署主密钥加密保存可解密副本，查看响应禁止缓存。
• 远程取件地址必须使用有效期足够的 HTTPS 地址，并符合服务端允许域名。
• 成片存储在私有腾讯云 COS；生产对象当前按 7 天保留策略清理，签名 URL 默认约 1 小时有效。
• 不要记录 API Key、上游账号 Token、COS 密钥或完整签名 URL。
• 管理接口不属于公共接入契约，公网由独立认证和 Nginx 路径规则保护。