接口基础

鉴权

在 config.json 里设置 api_key 后，除 /health 外的所有接口都需要携带密钥，两种方式等价：

X-API-Key: <你的 API Key>

Authorization: Bearer <你的 API Key>

缺失或错误时返回：

{ "success": false, "output": "", "error": "unauthorized: missing or invalid API key" }

HTTP 状态码为 401。

返回格式

所有接口统一返回三段结构：

{
  "success": true,
  "output": {},
  "error": ""
}

失败时 success 为 false，原因写在 error 里。判断结果请以 success 字段为准，不要只看 HTTP 状态码。

草稿 ID

create_draft 生成的 draft_id 形如 dfd_cat_<时间戳>_<随机串>。它同时是：

• 后续所有 add_* 接口的入参
• 草稿缓存的键
• 导出目录名和下载链接里的标识

草稿保存在服务端进程内存里，服务重启后需要重新创建。

素材 URL 限制

服务端会校验传入的素材地址：

• 只允许 http / https
• 默认拦截解析到内网、回环、链路本地地址的域名（防止 SSRF）
• 如果在 config.json 里配置了 allowed_media_hosts，则只放行白名单域名

常见错误

现象	原因
unauthorized	没带 API Key 或 Key 不匹配
draft 'xxx' is not in cache	草稿 ID 不存在，或服务重启过，需要重新创建
video_url rejected	URL 协议不支持，或指向内网地址
draft_id is required	请求体缺少 draft_id