跳到主要内容

视频模型

视频模型通过 Prysm 的 OpenAI 兼容视频接口调用。接口是异步任务模式：创建请求会先返回视频任务 ID，任务完成后再查询状态并下载 MP4。

先准备三个值​

  • base_url：{{BASE_URL}}
  • api_key：控制台里的 Prysm API 密钥
  • model：模型市场中显示的视频模型名，例如 volcengine/doubao-seedance-2-0-260128

基本流程​

  1. 调用 POST {{BASE_URL}}/v1/videos 创建视频任务。
  2. 从响应中记录 id，作为后续查询和下载用的 VIDEO_ID。
  3. 调用 GET {{BASE_URL}}/v1/videos/{VIDEO_ID} 查询任务状态。
  4. 当状态为 completed 时，响应包含 result.url 字段，提供临时视频 URL。 调用 GET {{BASE_URL}}/v1/videos/{VIDEO_ID}/content 获取 307 跳转到上游视频 URL（不占用网关带宽）。

客户端可以轮询状态；如果客户端没有持续轮询，后台也会继续处理任务状态和完成态计费。用户侧要展示或下载结果时，仍需要使用 VIDEO_ID 查询状态或下载内容。

文生视频​

curl -sS -X POST "{{BASE_URL}}/v1/videos" \
  -H "Authorization: Bearer YOUR_PRYSM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "volcengine/doubao-seedance-2-0-260128",
    "prompt": "A small paper boat floating on a calm blue pond, soft morning light, cinematic camera movement, no text, no subtitles.",
    "seconds": 5,
    "size": "1280x720"
  }'

xAI Grok 视频模型示例：

curl -sS -X POST "{{BASE_URL}}/v1/videos" \
  -H "Authorization: Bearer YOUR_PRYSM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A small paper boat floating on a calm blue pond, cinematic lighting, no text.",
    "seconds": 5,
    "size": "1280x720"
  }'

图生视频​

简单单图参考可以使用 input_reference，值为可公网访问的 HTTPS 图片 URL。

curl -sS -X POST "{{BASE_URL}}/v1/videos" \
  -H "Authorization: Bearer YOUR_PRYSM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "volcengine/doubao-seedance-2-0-260128",
    "prompt": "Animate the product image with a slow commercial camera push-in, clean highlights, no text, no subtitles.",
    "input_reference": "https://ark-project.tos-cn-beijing.volces.com/doc_image/r2v_tea_pic1.jpg",
    "seconds": 5,
    "size": "1280x720"
  }'

如果需要传多图或 provider 原生多模态结构，使用 extra_body.content：

{
  "model": "volcengine/doubao-seedance-2-0-260128",
  "prompt": "Animate this reference image.",
  "seconds": 5,
  "size": "1280x720",
  "extra_body": {
    "content": [
      {"type": "text", "text": "Animate this reference image."},
      {"type": "image_url", "image_url": {"url": "https://example.com/product.png"}}
    ]
  }
}

视频生视频​

视频参考输入同样可以放在 input_reference 中。视频文件需要先托管为可访问的 HTTPS URL。

curl -sS -X POST "{{BASE_URL}}/v1/videos" \
  -H "Authorization: Bearer YOUR_PRYSM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "volcengine/doubao-seedance-2-0-260128",
    "prompt": "Keep the same subject and lighting, extend the motion with a smooth cinematic camera move, no text, no subtitles.",
    "input_reference": {
      "type": "video_url",
      "video_url": {
        "url": "https://example.com/input.mp4"
      }
    },
    "seconds": 5,
    "size": "1280x720"
  }'

多段参考或更复杂的 provider 原生参数使用 extra_body.content：

{
  "model": "volcengine/doubao-seedance-2-0-260128",
  "prompt": "Create a new shot using the motion and style of the reference video.",
  "seconds": 5,
  "size": "1280x720",
  "extra_body": {
    "content": [
      {"type": "text", "text": "Create a new shot using the motion and style of the reference video."},
      {"type": "video_url", "video_url": {"url": "https://example.com/input.mp4"}}
    ]
  }
}

编辑和延长视频​

Prysm 提供 /v1/videos/edits 和 /v1/videos/extensions 端点，分别用于编辑已有视频和延长视频时长。

视频编辑（xAI Grok 示例）：

curl -sS -X POST "{{BASE_URL}}/v1/videos/edits" \
  -H "Authorization: Bearer YOUR_PRYSM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video": {
      "id": "cgt-xxx"
    },
    "prompt": "Change the background to a sunset beach scene.",
    "seconds": 5,
    "size": "1280x720"
  }'

视频延长（xAI Grok 示例）：

curl -sS -X POST "{{BASE_URL}}/v1/videos/extensions" \
  -H "Authorization: Bearer YOUR_PRYSM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video": {
      "id": "cgt-xxx"
    },
    "seconds": 5,
    "size": "1280x720"
  }'
  • /v1/videos/edits：根据 prompt 指令编辑源视频。
  • /v1/videos/extensions：延长源视频时长，可选的 prompt 指定延续内容。
  • 这两个端点均使用 video.id 指定源视频任务 ID，返回新的视频任务 ID。

查询状态​

curl -sS \
  -H "Authorization: Bearer YOUR_PRYSM_API_KEY" \
  "{{BASE_URL}}/v1/videos/VIDEO_ID"

常见状态：

状态含义
queued / running / processing任务仍在生成中
completed视频已生成完成
failed任务失败
cancelled任务已取消
expired任务已过期

当任务达到 completed 时，响应包含 result 对象：

{
  "id": "cgt-xxx",
  "status": "completed",
  "result": {
    "url": "https://media.x.ai/.../video.mp4",
    "duration": 5.0,
    "width": 1280,
    "height": 720,
    "format": "mp4"
  },
  "expires_at": "2026-07-30T12:00:00Z"
}
  • result.url 是临时 URL，请尽快使用。
  • result.duration、result.width、result.height、result.format 提供媒体元数据（provider 相关，可能为空）。
  • expires_at 仅当上游提供准确的过期时间时存在。

下载 MP4​

# 307 跳转到上游视频 URL（不占用网关带宽）
curl -L -H "Authorization: Bearer YOUR_PRYSM_API_KEY" \
  "{{BASE_URL}}/v1/videos/VIDEO_ID/content" \
  --output video.mp4

需要 -L（或 --location）参数让 curl 跟随 307 跳转。Prysm 网关不下载或中转视频字节，直接跳转到上游媒体服务器。

常用参数​

参数类型说明
modelstring控制台或模型市场显示的视频模型名
promptstring视频生成指令
secondsnumber期望视频时长
sizestring常用值：1280x720、720x1280、1920x1080、1080x1920
input_referencestring / object图片或视频参考 URL；字符串会按图片 URL 处理
extra_body.contentarrayprovider 原生多模态输入，适合多图、视频参考和高级参数
extra_body.durationnumberprovider 原生时长参数；存在时优先于 seconds
extra_body.ratiostringprovider 原生画幅比例，例如 16:9 或 9:16
extra_body.resolutionstringprovider 原生分辨率，例如 720p 或 1080p
extra_body.seednumberprovider 支持时用于固定随机种子
extra_body.watermarkbooleanprovider 支持时控制水印
referencesarrayxAI 参考图片模式：最多 7 个图片 URL 的数组
video.idstring编辑/延长模式：源视频任务 ID

计费说明​

  • 视频任务在 provider 确认 completed 后入账。
  • 创建任务、查询状态和下载内容属于任务生命周期操作。
  • 同一个已完成任务重复查询时，只会按完成态结果入账一次。
  • failed、cancelled、expired 等非成功终态不会按完成视频入账。
  • 图生视频、视频生视频、不同分辨率和不同时长可能对应不同消耗，具体以用量记录和收支明细为准。
  • xAI 任务优先使用上游响应中的 cost_in_usd_ticks / 10,000,000,000 计算实际美元费用。当上游用量不可用时，系统按分辨率及输入媒体类型回退到静态模型价格。

排查问题​

现象检查项
401 或 403API key 是否正确、是否有目标视频模型权限
404base_url、/v1/videos 路径或 VIDEO_ID 是否正确
400size、seconds、input_reference 或 extra_body.content 格式是否正确
图片或视频参考无法使用参考文件是否为可公网访问的 HTTPS URL
任务长时间未完成查询任务状态，并在日志中记录请求时间、模型名和 VIDEO_ID
/content 返回 307任务已完成，跟随跳转下载视频
/content 返回 409任务仍在处理中，稍后重试
/content 返回 410任务已过期或已取消，结果不再可用
/content 返回 422任务失败

Seedance 2.5​

模型 ID：volcengine/doubao-seedance-2-5-260628（doubao-seedance-2-5-260628）。

任务类型​

Seedance 2.5 通过 POST /v1/videos 支持五种任务类型：

任务类型触发条件强制约束
文生视频仅文本ratio/duration 无特殊限制
首帧/首尾帧content 含 role=first_frame（可选 last_frame）ratio 必须为 adaptive
参考生视频含 reference_image/reference_video/reference_audioratio/duration 无特殊限制
视频编辑omni_reference_task_type=edit必须含 reference_video；ratio 必须 adaptive；duration 必须 -1；参考视频时长 4~30 秒
视频延长omni_reference_task_type=extend必须含 reference_video；ratio 必须 adaptive；duration 为 -1 或 4~30

缺省即合法：官方默认 ratio=adaptive、duration=-1。适配器不推断任务类型——仅凭 reference_video 无法区分参考、编辑与延长。

原生 extra_body.content 用法​

extra_body.content 对所有 Volcengine Seedance 模型（2.0 和 2.5）开放。

  • 互斥规则：extra_body.content 与 input_reference/image/references 不得同时出现。
  • prompt 与文本合并：prompt 必填且非空。若 content[] 已含有效文本项（type="text" 且 text 非空非纯空白），完整保留所有文本项并忽略 prompt；否则清除空文本项，在数组开头插入 {"type":"text","text":prompt}。

extra_body 可透传参数​

以下参数通过 extra_body 直接透传至方舟：

omni_reference_task_type、output_format（mp4/mov）、generate_audio、camera_fixed、draft、frames、service_tier、tools、safety_identifier、execution_expires_after。

分辨率限制​

Seedance 2.5 仅支持 480p 和 720p。传入 1080p 或 4k 会被本地校验拒绝。受限任务（编辑、延长、首尾帧）传入 size 会被拒绝，应改用 extra_body={"ratio":"adaptive","resolution":"720p"}。

素材上限​

最多 30 张图片 + 10 个视频 + 10 个音频（共 50 个素材），音视频总时长 30 秒。

输出格式 MOV​

在 extra_body 中设置 "output_format":"mov"。网关通过 307 跳转到上游预签名 URL，MOV 文件由方舟直接提供。注意播放器对 MOV 的兼容性。

48 小时本地超时​

extra_body 中的 execution_expires_after 原样透传至方舟。本地 execution_expires_at 最长按 172800 秒（48 小时）计算。超时后任务被置为 expired/free——不可逆终态，不再访问上游，迟到的 succeeded 不改变状态也不扣费。

示例​

文生视频：

from litellm import video_generation

response = video_generation(
    model="volcengine/doubao-seedance-2-5-260628",
    prompt="A paper boat floating on a calm blue pond, soft morning light, cinematic camera movement, no text, no subtitles.",
)

首尾帧：

response = video_generation(
    model="volcengine/doubao-seedance-2-5-260628",
    prompt="Add motion to this scene, smooth camera pan, no text, no subtitles.",
    extra_body={
        "content": [
            {"type": "text", "text": "Add motion to this scene, smooth camera pan, no text, no subtitles."},
            {"type": "image_url", "image_url": {"url": "https://example.com/first_frame.png"}, "role": "first_frame"},
            {"type": "image_url", "image_url": {"url": "https://example.com/last_frame.png"}, "role": "last_frame"},
        ],
        "ratio": "adaptive",
    },
)

参考生视频（含图片、视频、音频）：

response = video_generation(
    model="volcengine/doubao-seedance-2-5-260628",
    prompt="Create a cinematic scene combining the reference elements, no text, no subtitles.",
    extra_body={
        "content": [
            {"type": "text", "text": "Create a cinematic scene combining the reference elements, no text, no subtitles."},
            {"type": "image_url", "image_url": {"url": "https://example.com/ref.png"}, "role": "reference_image"},
            {"type": "video_url", "video_url": {"url": "https://example.com/ref.mp4"}, "role": "reference_video"},
            {"type": "audio_url", "audio_url": {"url": "https://example.com/ref.mp3"}, "role": "reference_audio"},
        ],
    },
)

视频编辑：

response = video_generation(
    model="volcengine/doubao-seedance-2-5-260628",
    prompt="Change the background to a sunset beach scene, keep the subject, no text, no subtitles.",
    extra_body={
        "content": [
            {"type": "text", "text": "Change the background to a sunset beach scene, keep the subject, no text, no subtitles."},
            {"type": "video_url", "video_url": {"url": "https://example.com/input.mp4"}, "role": "reference_video"},
        ],
        "omni_reference_task_type": "edit",
        "ratio": "adaptive",
        "duration": -1,
        "output_format": "mov",
    },
)

视频延长：

response = video_generation(
    model="volcengine/doubao-seedance-2-5-260628",
    prompt="Continue the motion with the same style, smooth cinematic camera move, no text, no subtitles.",
    extra_body={
        "content": [
            {"type": "text", "text": "Continue the motion with the same style, smooth cinematic camera move, no text, no subtitles."},
            {"type": "video_url", "video_url": {"url": "https://example.com/input.mp4"}, "role": "reference_video"},
        ],
        "omni_reference_task_type": "extend",
        "ratio": "adaptive",
        "duration": 5,
    },
)