• 简体中文
  • 创建视频生成任务

    视频生成为异步任务:提交任务 → 轮询状态 → 获取结果。本页介绍通用任务格式的创建端点,文生 / 图生 / 首尾帧 / 多参考图 / 视频生视频等输入模式调用同一端点(见下方输入素材与生成模式)。可用模型与价格以 模型广场 实时显示为准。

    TIP

    除通用任务格式外,还支持可灵、即梦、豆包 / Seedance、Sora 等格式——前三者与厂商官方端点结构一致(豆包复用本端点),面向已有对应厂商 API 代码的用户。MiniMax-H3 同样复用本端点,但渠道参数有硬性差异(分辨率只支持 768p / 2K,文生视频必填画幅),见 MiniMax 格式。

    端点

    POST /v1/video/generations

    认证

    请求头携带 Bearer 令牌(令牌获取见接入地址与鉴权):

    Authorization: Bearer sk-你的令牌

    请求体

    字段类型必填说明
    promptstring是文本描述提示词,不能为空
    modelstring是模型名,填模型广场在售的视频模型名(网关按模型路由到对应渠道)
    imagestring否图生视频首帧图片(URL 或 Base64);带此字段按图生视频处理
    imagesstring[]否多图输入;只传一张时用 image 即可(网关会自动并入 images);传多张即为多参考图模式
    modestring否渠道专属参数。可灵渠道为分辨率档位:std(720p)/ pro(1080p)等,缺省 std
    sizestring否画幅,宽 x 高(如 1280x720)。可灵渠道只取宽高比(16:9 / 9:16 / 1:1),分辨率数值本身丢弃,分辨率档位由 mode 决定
    durationinteger否时长(秒),网关校验 1 ~ 3600。可灵渠道缺省 5
    secondsstring否时长的字符串形式,与 duration 二选一
    input_referencestring否参考素材输入(部分渠道支持)
    metadataobject否扩展参数对象,网关整体合并进上游请求体:可灵渠道可传 negative_prompt、image_tail、callback_url、external_task_id 等并覆盖默认值
    metadata.first_frame_url / metadata.last_frame_urlmetadatastring首尾帧生视频:首帧 / 尾帧图片 URL,两张同时传(与 images 参考图互斥)
    metadata.video_urlsmetadatastring[]视频生视频:源视频 URL 列表,传多个即多参考视频
    metadata.audio_urlsmetadatastring[]参考音频(mp3 / wav),部分渠道配合 metadata.generate_audio 使用
    WARNING

    网关(new-api rc.25)只接受上表字段。width、height、fps、seed、n、response_format、user 等字段传入后会被静默丢弃——不报错、也不生效:画幅请用 size + mode 控制,时长请用 duration。注意渠道差异:豆包(Seedance)渠道的时长要用 seconds(顶层 duration 在该渠道不生效),画幅与分辨率走 metadata,详见豆包 / Seedance 格式。各模型实际支持的取值(时长档位、分辨率等)以模型广场模型详情和实际响应为准。

    输入素材与生成模式

    同一端点按传入的素材字段自动分流生成模式:

    模式触发方式
    文生视频只传 prompt
    图生视频image / images 传 1 张图
    多参考图images 传多张图,每张作为参考素材
    首尾帧生视频metadata.first_frame_url + metadata.last_frame_url 同时传两张
    视频生视频metadata.video_urls 传源视频,传多个即多参考视频
    参考音频metadata.audio_urls 配合 metadata.generate_audio(渠道支持为准)

    素材约束:图片 png / jpg / jpeg / webp,视频 mp4 / mov / webm,音频 mp3 / wav;URL 必须公网可直达(优先境内 CDN / OSS,境外图床可能被上游拦截);传多个素材时在 prompt 中说明各素材的用途。

    WARNING

    素材字段全部经 metadata 整体透传上游,网关不校验取值;顶层传 first_frame_url 等字段会被静默丢弃。各模型支持的输入模式不同(豆包 / 可灵 / MiniMax-H3 等渠道差异见各自格式页),以模型广场模型详情与渠道报错为准。

    请求示例

    以下场景 3 ~ 5 以 MiniMax-H3 为例(该渠道 metadata.resolution / ratio 为必填,见 MiniMax 格式);其余模型替换 model 并按各自渠道要求传参。

    cURL
    Python
    Node.js
    # 场景 1:文生视频
    curl -X POST https://api-model.shuntianchuang.cn/v1/video/generations \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-你的令牌" \
      -d '{
        "model": "kling-video-v2.5-turbo",
        "prompt": "一只橘猫在草地上追蝴蝶,电影感镜头,缓慢推近",
        "duration": 5,
        "size": "1280x720",
        "mode": "std"
      }'
    # 场景 2:图生视频(image 传首帧图片 URL 或 Base64)
    curl -X POST https://api-model.shuntianchuang.cn/v1/video/generations \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-你的令牌" \
      -d '{
        "model": "kling-video-v2.5-turbo",
        "prompt": "让画面中的猫跑起来,镜头缓慢推近",
        "image": "https://example.com/first-frame.jpg"
      }'
    # 场景 3:首尾帧生视频(首帧 + 尾帧经 metadata 透传)
    curl -X POST https://api-model.shuntianchuang.cn/v1/video/generations \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-你的令牌" \
      -d '{
        "model": "MiniMax-H3",
        "prompt": "从首帧的清晨天空过渡到尾帧的黄昏海岸,镜头缓慢横移",
        "metadata": {
          "resolution": "768p",
          "ratio": "16:9",
          "first_frame_url": "https://example.com/first-frame.jpg",
          "last_frame_url": "https://example.com/last-frame.jpg"
        }
      }'
    # 场景 4:多参考图(images 传多张,每张作为参考素材)
    curl -X POST https://api-model.shuntianchuang.cn/v1/video/generations \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-你的令牌" \
      -d '{
        "model": "MiniMax-H3",
        "prompt": "第一张图提供主体形象,第二张图提供背景风格,让主体在该背景中动起来",
        "images": [
          "https://example.com/ref-1.jpg",
          "https://example.com/ref-2.jpg"
        ],
        "metadata": { "resolution": "768p" }
      }'
    # 场景 5:视频生视频(metadata.video_urls 传源视频,传多个即多参考视频)
    curl -X POST https://api-model.shuntianchuang.cn/v1/video/generations \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer sk-你的令牌" \
      -d '{
        "model": "MiniMax-H3",
        "prompt": "把视频内容转换为水彩画风格,保持原有动作",
        "metadata": {
          "resolution": "768p",
          "video_urls": ["https://example.com/source.mp4"]
        }
      }'

    响应

    提交成功返回任务对象,记住 task_id 用于查询:

    {
      "id": "task_xxxxxxxx",
      "object": "video",
      "task_id": "task_xxxxxxxx",
      "status": "queued",
      "model": "kling-video-v2.5-turbo",
      "created_at": 1769473000
    }

    请求校验失败(如 prompt 为空、duration 超出范围)返回 400 与错误说明:

    {
      "code": "invalid_seconds",
      "message": "seconds must be between 1 and 3600",
      "data": null
    }

    计费按任务完成时的实际用量结算(失败自动退还)。提交后轮询任务状态,见获取视频生成任务状态。