FrameAI

外观

火山标准格式

约 3904 字大约 13 分钟

火山标准格式

FrameAI 已提供火山 Ark v3 原生兼容路由。客户端可以直接使用火山标准请求体创建和查询视频任务，无需改成通用 /v1/video/generations 格式。

创建任务

POST https://mivsub.com/api/v3/contents/generations/tasks
Authorization: Bearer sk-你的中转key
Content-Type: application/json
{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "参考多张图片，生成一个人物在城市街头行走的电影感视频"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://example.com/person.jpg"
      }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://example.com/scene.jpg"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false,
  "watermark": false
}

创建成功后会返回一个中转侧任务 ID，例如：

{
  "id": "task_xxx"
}

查询任务

GET https://mivsub.com/api/v3/contents/generations/tasks/task_xxx
Authorization: Bearer sk-你的中转key

标准请求约定

截图中的 7 种创建方式都使用同一个火山标准创建地址，区别只在 content[] 中传入的素材类型：

POST https://mivsub.com/api/v3/contents/generations/tasks
Authorization: Bearer sk-你的中转key
Content-Type: application/json

下面示例中的 model、resolution、ratio、duration、generate_audio 和 watermark 可以按渠道实际支持范围调整。

文生视频标准格式

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "黄昏时分的海边公路，一辆复古汽车缓慢驶过，镜头平稳推进"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false,
  "watermark": false
}

图生视频标准格式

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "让画面中的人物自然转身，镜头缓慢推进"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://cdn.example.com/input/person.jpg"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "9:16",
  "duration": 5,
  "generate_audio": false,
  "watermark": false
}

多图参考标准格式

提示词使用 [Image 1]、[Image 2] 等标记对应图片，所有图片对象都使用 reference_image：

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "参考 [Image 1] 的人物、[Image 2] 的服装和 [Image 3] 的场景，生成城市街头行走的视频"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://cdn.example.com/reference/person.jpg"
      }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://cdn.example.com/reference/clothes.jpg"
      }
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://cdn.example.com/reference/scene.jpg"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false,
  "watermark": false
}

视频参考标准格式

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "参考 [Video 1] 的镜头节奏和运镜方式，将主体替换为一辆银色跑车"
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {
        "url": "https://cdn.example.com/reference/motion.mp4"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": false,
  "watermark": false
}

音频参考标准格式

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "参考 [Audio 1] 的节奏，生成霓虹城市夜景中人物慢慢走过街道的视频"
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {
        "url": "https://cdn.example.com/reference/music.mp3"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true,
  "watermark": false
}

视频+音频参考标准格式

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "参考 [Video 1] 的动作和镜头，参考 [Audio 1] 的节奏，生成舞者连续旋转的视频"
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {
        "url": "https://cdn.example.com/reference/dance.mp4"
      }
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {
        "url": "https://cdn.example.com/reference/beat.mp3"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "generate_audio": true,
  "watermark": false
}

图片+音频参考标准格式

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {
      "type": "text",
      "text": "参考 [Image 1] 中的产品外观，配合 [Audio 1] 的节奏，生成产品旋转展示的广告视频"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://cdn.example.com/reference/product.jpg"
      }
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {
        "url": "https://cdn.example.com/reference/product-music.mp3"
      }
    }
  ],
  "resolution": "720p",
  "ratio": "1:1",
  "duration": 5,
  "generate_audio": true,
  "watermark": false
}

标准字段速查

素材typeroleURL 字段
图片image_urlreference_imageimage_url.url
视频video_urlreference_videovideo_url.url
音频audio_urlreference_audioaudio_url.url

所有素材对象的 role 都必须位于对象外层。素材 URL 必须公网直连，不能依赖 Cookie、登录态或浏览器 Referer。

role 的正确位置

火山标准格式中，role 在 content[] 的图片对象外层：

{
  "type": "image_url",
  "role": "reference_image",
  "image_url": {
    "url": "https://example.com/image.jpg"
  }
}

下面这种内层 role 不符合火山标准：

{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/image.jpg",
    "role": "reference_image"
  }
}
结论：如果上游提示 role must be specified for image contents，优先检查客户端请求的顶层 content[].role 是否存在。FrameAI 会在内部转换时保留整个原始请求，不需要调用方把 content 放进 metadata。
## 鉴权与任务生命周期

火山标准视频接口是异步接口。创建请求只返回 FrameAI 公开任务 ID，视频文件需要通过查询接口获取。

POST 创建任务
  -> 返回公开任务 ID
  -> GET 查询 queued / processing
  -> GET 查询 succeeded / failed
  -> succeeded 时读取 content.video_url
项目约定
基础地址你的 FrameAI HTTPS 地址，例如 https://mivsub.com
创建路径POST /api/v3/contents/generations/tasks
查询路径GET /api/v3/contents/generations/tasks/{task_id}
鉴权Authorization: Bearer <FrameAI API Key>
请求格式application/json
任务类型异步任务
任务 IDFrameAI 公开任务 ID，不是上游原始任务 ID

创建和查询必须使用同一个 FrameAI 地址与 API Key。不要拿创建响应中的公开任务 ID 直接请求火山官方域名。

创建请求字段

字段类型必填说明
modelstring是视频模型名称，例如 doubao-seedance-2-0-260128
contentarray<object>是提示词和参考素材列表，至少应包含一个非空文本项
resolutionstring否输出分辨率，例如 480p、720p 或 1080p，以模型支持范围为准
ratiostring否输出比例，例如 16:9、9:16、1:1、4:3 或 3:4
durationinteger否视频时长，单位秒；标准格式推荐传 JSON 数字，实际范围以模型为准
generate_audioboolean否是否生成声音；只有支持音画同步的模型才会生效
watermarkboolean否是否添加上游水印
seedinteger否随机种子；相同种子不保证结果完全一致
framesinteger否指定输出帧数；仅在模型支持时使用
camera_fixedboolean否是否固定镜头；仅在模型支持时使用，不需要时应省略
return_last_frameboolean否是否在上游结果中返回尾帧信息
service_tierstring否服务等级或调度档位，以渠道支持值为准
execution_expires_afterinteger否任务等待执行的过期时间，以渠道单位和范围为准
callback_urlstring否上游任务回调地址；必须是公网 HTTPS 地址且能够接收上游请求
draftboolean否是否使用草稿模式；仅支持该能力的模型有效
safety_identifierstring否调用方提供的安全标识，用于上游安全审计
priorityinteger否任务优先级；仅在渠道支持时有效
toolsarray<object>否上游工具配置列表
tools[].typestring否工具类型，例如渠道支持的检索工具
字段透传：FrameAI 会完整保留原始火山请求字段并交给视频适配器。可选字段是否生效由模型、渠道权限和火山上游版本共同决定；不确定的字段应省略，不要传空字符串或 null。

duration 和通用接口 seconds 的区别

接口时长字段推荐类型
火山标准接口 /api/v3/contents/generations/tasksdurationinteger
FrameAI 通用接口 /v1/video/generationssecondsstring

标准接口示例：

{
  "duration": 5
}

通用接口示例：

{
  "seconds": "5"
}

FrameAI 会在内部把标准请求中的 duration 转成通用任务层使用的字符串时长，同时保留原始 duration 给火山适配器。客户端调用标准接口时不需要同时发送 seconds。

content[] 字段

content 是一个有顺序的数组。文本项提供提示词，媒体项提供图片、视频或音频参考。

字段类型适用 type必填说明
content[].typestring全部是text、image_url、video_url 或 audio_url
content[].textstringtext是视频提示词；多个文本项会按数组顺序合并
content[].rolestring媒体项是图片、视频、音频对应的参考角色
content[].image_urlobjectimage_url是图片地址对象
content[].image_url.urlstringimage_url是公网图片 URL 或 asset://<asset_id>
content[].video_urlobjectvideo_url是视频地址对象
content[].video_url.urlstringvideo_url是公网视频 URL 或渠道支持的素材 URI
content[].audio_urlobjectaudio_url是音频地址对象
content[].audio_url.urlstringaudio_url是公网音频 URL 或渠道支持的素材 URI

type 与 role 对照

素材typeroleURL 字段
提示词text不传text
图片参考image_urlreference_imageimage_url.url
视频参考video_urlreference_videovideo_url.url
音频参考audio_urlreference_audioaudio_url.url

媒体对象的 role 与 type 必须位于同一层，不能放进 image_url、video_url 或 audio_url 内部。

素材编号引用

提示词中的编号按同类媒体在 content[] 中出现的顺序对应：

  • 第一个图片对象对应 [Image 1]，第二个对应 [Image 2]。
  • 第一个视频对象对应 [Video 1]。
  • 第一个音频对象对应 [Audio 1]。
  • 编号用于在提示词里明确每个参考素材的用途，不是独立请求字段。

示例：

{
  "content": [
    {
      "type": "text",
      "text": "保持 [Image 1] 的人物外观，使用 [Video 1] 的运镜节奏，并跟随 [Audio 1] 的节拍"
    },
    {
      "type": "image_url",
      "role": "reference_image",
      "image_url": {
        "url": "https://cdn.example.com/person.png"
      }
    },
    {
      "type": "video_url",
      "role": "reference_video",
      "video_url": {
        "url": "https://cdn.example.com/camera.mp4"
      }
    },
    {
      "type": "audio_url",
      "role": "reference_audio",
      "audio_url": {
        "url": "https://cdn.example.com/beat.mp3"
      }
    }
  ]
}

创建任务响应

创建成功返回 HTTP 200 和 FrameAI 公开任务 ID：

{
  "id": "task_hnEiVXs6kMRny4o0Bww202B9Hg7nRrtf"
}

响应字段：

字段类型说明
idstringFrameAI 公开任务 ID，用于调用同一标准查询接口

创建响应只保证返回 id。任务状态、视频 URL、分辨率和实际时长需要通过查询接口获取。

查询任务请求

GET https://mivsub.com/api/v3/contents/generations/tasks/task_hnEiVXs6kMRny4o0Bww202B9Hg7nRrtf
Authorization: Bearer sk-frameai-xxxxxxxx

路径参数：

字段位置类型必填说明
task_idpathstring是创建接口返回的 FrameAI 公开任务 ID

查询请求没有请求体，不需要发送 Content-Type。

查询任务响应

处理中响应示例：

{
  "id": "task_hnEiVXs6kMRny4o0Bww202B9Hg7nRrtf",
  "model": "doubao-seedance-2-0-260128",
  "status": "processing",
  "created_at": 1786240800,
  "updated_at": 1786240812,
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9"
}

成功响应示例：

{
  "id": "task_hnEiVXs6kMRny4o0Bww202B9Hg7nRrtf",
  "model": "doubao-seedance-2-0-260128",
  "status": "succeeded",
  "created_at": 1786240800,
  "updated_at": 1786240860,
  "seed": 123456,
  "resolution": "720p",
  "duration": 5,
  "ratio": "16:9",
  "framespersecond": 24,
  "service_tier": "default",
  "content": {
    "video_url": "https://cdn.example.com/output/video.mp4"
  },
  "usage": {
    "completion_tokens": 1000,
    "total_tokens": 1000,
    "tool_usage": {
      "web_search": 0
    }
  }
}

失败响应示例：

{
  "id": "task_hnEiVXs6kMRny4o0Bww202B9Hg7nRrtf",
  "model": "doubao-seedance-2-0-260128",
  "status": "failed",
  "created_at": 1786240800,
  "updated_at": 1786240825,
  "error": {
    "code": "OutputVideoSensitiveContentDetected.PolicyViolation",
    "message": "The request failed because the output video may violate upstream policy"
  }
}

查询响应字段

字段类型出现条件说明
idstring始终FrameAI 公开任务 ID
modelstring始终创建任务时使用的模型名称
statusstring始终queued、processing、succeeded 或 failed
created_atinteger始终任务创建时间，Unix 秒
updated_atinteger始终任务最后更新时间，Unix 秒
seedinteger上游返回时实际使用的随机种子
resolutionstring上游或创建请求提供时输出分辨率
durationinteger上游或创建请求提供时视频时长，单位秒
ratiostring上游或创建请求提供时输出宽高比
framespersecondinteger上游返回时实际视频帧率
service_tierstring上游或创建请求提供时实际服务等级
toolsarray<object>上游或创建请求提供时使用的工具列表
contentobject生成结果可用时视频结果对象
content.video_urlstring成功时最终视频下载地址
usageobject上游返回时本次任务用量
usage.completion_tokensinteger上游返回时生成用量
usage.total_tokensinteger上游返回时总用量
usage.tool_usageobject使用工具时工具用量
usage.tool_usage.web_searchinteger使用网页检索时网页检索次数或用量
errorobject失败时任务失败信息
error.codestring失败时上游或 FrameAI 错误码
error.messagestring失败时任务失败详情

如果上游在处理中返回的 duration、resolution 或 ratio 是 null，FrameAI 会优先使用创建任务时保存的非空值补全查询响应。上游成功后返回了非空实际值时，则优先使用上游值。

状态处理

状态含义客户端行为
queued任务已创建，等待上游执行继续轮询
processing上游正在生成继续轮询
succeeded生成成功读取 content.video_url 并尽快下载或转存
failed生成失败读取 error.code 和 error.message

建议轮询间隔为 3 至 10 秒，并设置最大等待时间。不要同时高频查询同一个任务，也不要因为一次 processing 就重复创建任务。

素材 URL 要求

公网素材 URL 必须满足：

  • 使用 HTTPS 开头的服务端可访问地址。
  • 访问时不依赖 Cookie、浏览器登录态、Referer 或临时页面跳转。
  • 响应内容是实际图片、视频或音频，而不是 HTML 错误页。
  • 地址在任务创建和上游拉取期间保持有效。
  • 文件类型、大小、时长、分辨率和编码满足当前 Seedance 模型要求。

已经通过素材接口创建的素材，可在模型支持时使用：

{
  "type": "image_url",
  "role": "reference_image",
  "image_url": {
    "url": "asset://asset-xxxxxxxx"
  }
}

素材创建和查询方式见火山素材接口总览。

FrameAI 内部转换规则

客户端仍然发送本页定义的火山标准请求。FrameAI 内部会执行以下转换：

  1. 保留原始请求中的所有字段，供火山视频适配器继续解析和转发。
  2. 从 model 读取模型名称。
  3. 优先读取顶层 prompt；不存在时，按顺序合并所有 content[].type=text 的 text。
  4. 将 duration 转为内部通用任务层使用的字符串时长。
  5. 创建任务成功后返回 FrameAI 公开任务 ID，并保存公开 ID 与上游任务 ID 的映射。
  6. 查询任务时使用公开任务 ID，FrameAI 再查询对应上游任务并输出火山兼容响应。
不要重复包装：调用 /api/v3/contents/generations/tasks 时，content、resolution、ratio、duration 等字段都放在请求体顶层，不要再放进 metadata。

错误响应

请求体解析或本地校验失败时，通常返回 HTTP 4xx：

{
  "error": {
    "message": "invalid request body",
    "type": "invalid_request_error",
    "code": "invalid_request_error"
  }
}

上游任务创建失败时，错误结构可能包含火山上游错误码和请求 ID。任务已经创建、但生成阶段失败时，通过查询接口的 error 字段返回失败原因。

HTTP 状态码常见原因
400JSON 无效、model 缺失、content 结构错误、task_id 为空
401FrameAI API Key 缺失、无效或过期
403当前 Token、渠道或模型权限不足
404公开任务 ID 不存在或当前用户无权访问
429当前分组上游负载饱和或触发限流
500本地任务保存、响应解析或内部处理失败
502渠道凭证、代理或火山上游请求失败

常见字段错误

错误信息原因修复
role must be specified for image contents图片对象缺少外层 role在 content[] 图片对象中添加 "role": "reference_image"
reference media mode requires video role to be reference_video视频对象的 role 缺失或错误使用 "role": "reference_video"
素材拉取失败URL 不是公网直连、已过期或返回 HTML更换稳定的 HTTPS 直链或使用素材库 ID
OutputVideoSensitiveContentDetected.PolicyViolation上游输出安全或版权策略拦截修改提示词和参考素材，避免受限内容后重新创建
查询一直是 processing上游仍在生成或任务队列拥堵保持低频轮询并设置超时，不要重复提交
查询结果没有 content.video_url任务尚未成功或上游未返回结果地址先检查 status 和 error

调用检查清单

  1. 请求地址是 FrameAI 的 /api/v3/contents/generations/tasks，不是火山官方地址。
  2. Authorization 使用 FrameAI 分发的 Bearer Key。
  3. model 与渠道已开通的 Seedance 模型完全一致。
  4. 至少有一个非空 text 内容项。
  5. 图片、视频和音频对象的 role 位于素材对象外层。
  6. 所有公网素材 URL 都能由服务端直接访问。
  7. 标准接口使用 duration 数字，不同时传通用接口的 seconds。
  8. 创建响应只读取 id，查询时使用同一公开任务 ID。
  9. succeeded 后读取 content.video_url。
  10. 对结果 URL 尽快下载或转存，避免临时地址过期。
文本模型和火山视频接入手册
Copyright © 2026 FrameAI.