异步视频任务

使用统一任务接口提交视频生成，并通过轮询或回调获取结果

异步视频接口分为两步：先提交生成任务并保存返回的 id，再用该 ID 查询状态；完成后从 outputs 获取视频 URL。需要后台批量处理时，也可以设置 callback_url 接收结果。

新接入从这里开始

Seedance 2.0 / 2.5、MiniMax-H3、Veo 3.1、Kling 3.0 Turbo、Grok Imagine 1.5、Happy Horse 1.1 和 Gemini Omni Flash 都使用本页的统一任务格式。已有其他 /v1/videos 接入可继续使用侧栏“其他视频接口”中的页面，但 Veo 旧接口和旧模型名已经移除。

1. 选择模型

模型	支持的输入	时长与清晰度	适合场景
`seedance-2.0`	9 图 / 3 视频 / 3 音频；不支持首尾帧；支持人脸素材	仅 15 秒；仅 720p	质量优先
`seedance-2.0-fast`	9 图 / 3 视频 / 3 音频、首尾帧；支持人脸素材	4–15 秒；480p/720p	速度优先
`seedance-2.5`	最多 30 图 / 10 视频 / 3 音频、首尾帧；支持人脸素材	4–30 秒；480p/720p	更长成片、多参考素材
`MiniMax-H3`	最多 9 图 / 3 视频 / 3 音频，可组合使用	4–15 秒；768P/2K	多参考素材或 2K 输出
`veo-3.1-generate-preview`	文本、最多 3 张参考图或成对首尾帧	4/6/8 秒；720p/1080p	Veo 质量优先
`veo-3.1-fast-generate-preview`	文本或成对首尾帧；不支持普通参考图	4/6/8 秒；720p/1080p	Veo 速度优先
`kling-3.0-turbo`	文字或 1 张首帧	3–15 秒；720p/1080p	快速文生视频或首帧图生视频
`grok-imagine-1.5`	必须提供 1 张首帧	3–15 秒；480p/720p	让已有画面自然动起来
`happy-horse-1.1`	文字、最多 9 张参考图或 1 张首帧	3–15 秒；720p/1080p	多人物、多产品或多风格参考
`gemini-omni-flash`	文字、最多 5 张参考图	3–10 秒；720p	快速生成横屏或竖屏短视频

请根据时长、清晰度、速度和素材限制选择具体模型。模型页会列出完整字段、组合限制和输出尺寸。

2. 提交任务

POST https://cdn.12ai.org/v1/task/submit
Authorization: Bearer $API_KEY
Content-Type: application/json

请求体

字段	类型	必填	说明
`model`	string	是	模型名称，必须与对应模型页一致
`input`	object	是	生成参数；可用字段和限制由模型决定
`callback_url`	string	否	任务结束后的通知地址，仅支持 `http` 或 `https`

所有模型都在 input 中接收 prompt，常见字段如下：

字段	类型	说明
`prompt`	string	提示词，必填，最多 5000 个字符
`duration`	integer	视频秒数，支持范围见模型页
`aspect_ratio`	string	画面比例，例如 `16:9`、`9:16`
`resolution`	string	清晰度，例如 `720p`、`1080p`
`audio`	boolean	是否生成音频；只在模型明确支持时传入
`n`	integer	生成数量，目前仅支持 `1`

最小请求

curl https://cdn.12ai.org/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "input": {
      "prompt": "明亮的产品展示视频，镜头平稳推进，真实商业摄影风格",
      "duration": 10,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "audio": true
    }
  }'

成功后立即返回任务 ID，此时视频通常仍在排队：

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "queued",
  "phase": "queued",
  "created_at": 1760000000,
  "progress": null
}

参考素材格式

图片、视频和音频字段都使用数组。数组项可以直接写 URL：

"https://example.com/reference.jpg"

也可以用对象提供素材 URL：

{
  "url": "https://example.com/reference.jpg"
}

支持公网 http/https URL、data URI 和纯 base64。对象通常可使用 url、image、video、audio 中的一个字段，具体以模型页为准。

本地路径、file:// 和对象中的 path 字段无法被服务端读取。本地文件需要先上传到可公开访问的地址，或转换为 data URI / base64。

3. 查询结果

将提交响应中的 id 拼到查询路径：

curl https://cdn.12ai.org/v1/task/task_xxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $API_KEY"

`status`	含义	下一步
`queued`	正在排队	继续等待
`processing` / `in_progress`	正在处理或生成	3–5 秒后再次查询
`completed`	生成成功	从 `outputs` 读取视频 URL
`failed`	生成失败	查看 `error` 并停止轮询

生成过程可能依次经过 materializing_references、uploading_references、submitting_generation 和 generating 等 phase。业务判断以 status 为准，进入 completed 或 failed 后停止轮询。

完成响应示例：

{
  "id": "task_xxxxxxxxxxxxxxxx",
  "status": "completed",
  "phase": "completed",
  "outputs": [
    "https://img.12ai.org/videos/task_xxxxxxxxxxxxxxxx_0.mp4"
  ],
  "error": null,
  "completed_at": 1760000100
}

4. 接收回调（可选）

提交时传入 callback_url 后，任务进入 completed 或 failed 时，系统会向该地址发送 POST 请求，请求体与查询响应一致。

处理建议	原因
快速返回 2xx	避免回调连接长时间阻塞
按任务 ID 幂等处理	同一任务可能重复通知
校验 `id`	将回调关联到本地业务记录
尽快转存 `outputs`	避免长期依赖临时结果 URL

Python 完整示例

import time
import requests

API_BASE = "https://cdn.12ai.org"
API_KEY = "sk-xxx"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

task = requests.post(
    f"{API_BASE}/v1/task/submit",
    headers=headers,
    json={
        "model": "seedance-2.0-fast",
        "input": {
            "prompt": "明亮的产品展示视频，镜头平稳推进，真实商业摄影风格",
            "aspect_ratio": "16:9",
            "resolution": "720p",
            "duration": 10,
            "audio": True,
        },
    },
    timeout=60,
).json()

task_id = task["id"]

while True:
    result = requests.get(
        f"{API_BASE}/v1/task/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=60,
    ).json()

    if result["status"] == "completed":
        print(result["outputs"][0])
        break

    if result["status"] == "failed":
        raise RuntimeError(result.get("error", "任务失败"))

    time.sleep(4)

异步视频任务

On this page