视频生成 API

视频生成是异步任务：提交后立即返回任务 ID，之后轮询任务状态，完成后下载视频。只有视频生成模型（模型目录里按「秒」计价的模型）可以调用这些接口，对话模型调用会返回 400。

每个视频模型支持一种或两种协议，模型详情页的「如何调用」会列出该模型可用的接口。模型不支持的入口会直接返回 400 并提示应改用哪个入口，平台不会替你换协议。

模型名可以写模型目录里的完整 ID，也可以写去掉命名空间的官方 ID（如 <model-id>）。

生命周期与计费

1. 提交：按「请求秒数 × 每秒价格」冻结余额（预授权）。余额不足返回 402 insufficient_balance，不会创建任务。
2. 生成中：状态为 queued → in_progress。冻结的金额会显示在控制台【用量分析 → 请求日志 → 视频生成任务】里。
3. 完成：按实际生成秒数（不超过请求秒数）结算一次，多冻结的部分自动释放；之后可在请求日志中按 request_id 查到这笔扣费。
4. 失败 / 取消 / 超时：不计费，冻结的金额全部释放。

平台会在后台持续推进未完成的任务，结算不依赖你是否轮询。

协议一：OpenAI Videos（/v1/videos）

提交任务

POST https://api.admesh.ai/v1/videos

curl https://api.admesh.ai/v1/videos \
  -H "Authorization: Bearer $ADMESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "prompt": "A corgi running on the beach at sunset, cinematic",
    "seconds": "8"
  }'

返回视频对象，id 即任务 ID（形如 video_…）：

{ "id": "video_8f2a…", "object": "video", "model": "<model-id>", "status": "queued", "progress": 0, "seconds": "8", "created_at": 1762650000 }

查询状态

curl https://api.admesh.ai/v1/videos/$VIDEO_ID \
  -H "Authorization: Bearer $ADMESH_API_KEY"

status 为 queued / in_progress / completed / failed；completed 时 seconds 是实际计费秒数，失败时 error.code 给出原因。

下载视频

curl -L https://api.admesh.ai/v1/videos/$VIDEO_ID/content \
  -H "Authorization: Bearer $ADMESH_API_KEY" \
  -o video.mp4

只有 completed 的任务可以下载。可选查询参数 variant=video|thumbnail|spritesheet（需模型支持）。

列出与删除

• GET /v1/videos：列出你最近的视频任务。
• DELETE /v1/videos/{id}：删除视频任务。

协议二：任务接口（/v1/video/generations）

提交任务

curl https://api.admesh.ai/v1/video/generations \
  -H "Authorization: Bearer $ADMESH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "prompt": "A corgi running on the beach at sunset, cinematic",
    "duration": 5
  }'

返回 { "task_id": "video_…", "id": "video_…", "status": "queued", … }。

查询状态

curl https://api.admesh.ai/v1/video/generations/$TASK_ID \
  -H "Authorization: Bearer $ADMESH_API_KEY"

返回 { "code": "success", "data": { "task_id": "…", "status": "IN_PROGRESS", "progress": "40%", … } }。data.status 为 QUEUED / IN_PROGRESS / SUCCESS / FAILURE；SUCCESS 时 data.result_url 是视频下载地址（即上面的 /v1/videos/{id}/content，下载同样需要带 API Key）。

请求字段

请求体只接受以下字段，请勿传入其它参数：

字段	协议	说明
model	两者	必填，视频模型 ID
prompt	两者	文本描述；OpenAI Videos 必填，任务接口与 image 至少给一个
seconds	OpenAI Videos	视频秒数，字符串或整数（如 "8"）；不传按模型默认秒数
duration	任务接口	视频秒数，整数；不传按模型默认秒数
size	两者	分辨率，如 1280x720（取值以模型支持为准）
input_reference	OpenAI Videos	参考图（图生视频，需模型支持）
image	任务接口	参考图（图生视频，需模型支持）

• 秒数必须是正整数，且不超过模型的最长秒数；部分模型只支持固定几档秒数（如 5 / 10 秒），以模型详情页为准。
• 不支持 stream；n 只能为 1（一次一个视频）。

常见错误

HTTP	code	说明
400	invalid_request	模型不是视频模型 / 模型不支持该入口 / 秒数非法或超过上限 / 视频尚未完成就下载
401	invalid_api_key	API Key 无效或已撤销
402	insufficient_balance	余额不足以冻结「秒数 × 每秒价格」
403	model_not_allowed	该 API Key 没有开通这个模型
404	not_found	任务不存在，或不属于当前账户
429	rate_limit_exceeded	触达限流，稍后重试
502 / 503 / 504	upstream_error / model_provider_unavailable / upstream_timeout	服务暂时不可用，提交未成功时不计费

任务失败时，OpenAI Videos 在 error.code 中给出原因（如 upstream_timeout 表示生成超时），任务接口在 data.fail_reason 中给出说明。失败的任务不计费。