视频接入

本页说明如何接入 We-AI 视频生成服务，包括请求结构、媒体限制、异步任务处理和常见错误。

接口信息

具体 Base URL 和请求路径以 We-AI 平台当前提供的信息为准。

一、接入前准备

调用视频生成服务前，请准备：

• We-AI API Key。
• 可公开访问的图片、视频或音频 URL；如接口支持上传文件或 Base64，也应先转换为对应的媒体对象。
• 完整的视频模型名称、提示词和输出时长。

API Key 通过请求头传递：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

不要把真实 API Key 写进前端代码、公开仓库、截图或聊天记录。

二、支持的模型

当前支持以下模型：

对外模型名称	类型	分辨率
seedance-2.0-480p	标准版	480p
seedance-2.0-720p	标准版	720p
seedance-2.0-1080p	标准版	1080p
seedance-2.0-fast-480p	Fast 版	480p
seedance-2.0-fast-720p	Fast 版	720p

调用时注意：

• model 是必填字段，必须传递表格中的完整模型名称。
• Fast 版目前只开放 480p 和 720p，不存在 seedance-2.0-fast-1080p。
• 不能只传 seedance-2.0 或 seedance-2.0-fast。
• 使用 seedance-2.0-1080p 时，生成时长最多为 12 秒。
• 模型列表和价格以后可能变化。业务代码应从配置或模型表读取，不要散落硬编码。

模型名称已经包含类型和分辨率，请勿再单独传递 resolution。

三、媒体限制

单次视频生成请求需要遵守以下限制：

资源类型	单次上限	说明
普通参考图	4 张	不包含首帧和尾帧
参考视频	3 段	所有参考视频累计不超过 15 秒
参考音频	1 段	超过 1 段会直接拒绝
首帧和尾帧	合计 2 张	单独计数，不占普通参考图额度

例如：

• 4 张普通参考图 + 1 张首帧 + 1 张尾帧：可以提交。
• 5 张普通参考图 + 1 张首帧：不能提交。
• 3 段参考视频，总时长正好 15 秒：可以提交。
• 3 段参考视频，总时长 15.01 秒：不能提交。

视频时长以服务端探测到的真实时长为准，不以客户端填写值为最终依据。为减少提交失败，建议在发送请求前先读取媒体信息并完成同样的限制检查。

四、请求结构

标准化后的视频生成请求示例如下：

{
  "model": "seedance-2.0-fast-480p",
  "prompt": "人物在城市街道中向前走",
  "reference_images": [
    { "url": "https://example.com/ref-1.jpg" }
  ],
  "reference_videos": [
    {
      "url": "https://example.com/ref-1.mp4",
      "duration_seconds": 6.5
    }
  ],
  "reference_audios": [
    {
      "url": "https://example.com/ref-1.mp3",
      "duration_seconds": 8
    }
  ],
  "first_frame": {
    "url": "https://example.com/first.jpg"
  },
  "last_frame": {
    "url": "https://example.com/last.jpg"
  },
  "duration_seconds": 5
}

字段说明：

字段	类型	说明
model	string	必填；使用支持列表中的完整模型名称
prompt	string	视频内容、动作、镜头和风格描述
reference_images	array	普通参考图，最多 4 张
reference_videos	array	参考视频，最多 3 段且累计不超过 15 秒
reference_audios	array	参考音频，最多 1 段
first_frame	object	可选首帧
last_frame	object	可选尾帧
duration_seconds	number	期望输出的视频时长；1080p 最多 12 秒

没有使用的媒体字段可以省略或传空数组。first_frame 和 last_frame 都为空时，首尾帧数量为 0。

客户端字段兼容

部分客户端可能使用 image、images、video、videos 或 audio。接入时应按照实际接口协议映射到标准字段，不要把 first_frame 或 last_frame 计入普通参考图数量。

五、任务处理流程

视频生成是异步任务，通常按以下流程处理：

1. 提交视频生成请求。
2. 保存接口返回的任务 ID。
3. 使用该任务 ID 查询任务状态。
4. 任务完成后读取结果 URL。
5. 任务失败、取消或超时时，停止轮询并处理错误。

常见任务状态包括：

状态	含义	客户端操作
queued	已进入队列	等待后继续查询
processing	正在生成	按合理间隔继续查询
completed	生成完成	读取并保存结果 URL
failed	生成失败	根据错误码修正请求或稍后重试
cancelled	任务已取消	停止查询
expired / timeout	任务已超时	停止查询，必要时重新提交

建议每 3 至 5 秒查询一次，不要高频轮询。客户端还应设置最大等待时间，并使用自己的 request_id 防止网络重试造成重复任务。

六、错误响应

错误响应采用统一结构：

{
  "error": {
    "code": "reference_video_duration_limit_exceeded",
    "message": "参考视频最多 3 段，累计时长不能超过 15 秒",
    "details": {
      "count": 3,
      "duration_seconds": 16.2,
      "max_count": 3,
      "max_duration_seconds": 15
    }
  }
}

常见错误码：

错误码	HTTP 状态	处理方式
reference_images_limit_exceeded	400	将普通参考图减少到 4 张以内
reference_videos_limit_exceeded	400	将参考视频减少到 3 段以内
reference_video_duration_limit_exceeded	400	将参考视频累计时长减少到 15 秒以内
reference_audios_limit_exceeded	400	只保留 1 段参考音频
first_last_frames_limit_exceeded	400	首帧和尾帧合计不超过 2 张
media_duration_unavailable	422	检查视频 URL、格式和文件完整性
no_available_account	503	暂无可用资源，稍后重试
account_rate_limited	503	服务暂时被限流，降低频率后重试
upstream_auth_failed	502	联系平台检查上游服务状态
upstream_task_failed	502	检查请求内容，必要时稍后重试
task_timeout	504	任务超时，等待后重新提交

对 400 和 422 错误，应先修改请求，不要原样重试。对 502、503 和 504 错误，可以采用指数退避重试，并限制最大重试次数。

七、接入检查清单

正式接入前，建议依次验证：

• API Key 已通过 Authorization: Bearer YOUR_API_KEY 传递。
• model 已填写支持列表中的完整名称，没有使用缩写或不存在的 Fast 1080p 模型。
• 使用 seedance-2.0-1080p 时，duration_seconds 不超过 12。
• 媒体 URL 可由服务端公开访问，没有登录态、临时 Cookie 或防盗链限制。
• 普通参考图不超过 4 张。
• 参考视频不超过 3 段，真实累计时长不超过 15 秒。
• 参考音频不超过 1 段。
• 首帧和尾帧合计不超过 2 张，且没有占用普通参考图额度。
• 客户端保存任务 ID，并按合理间隔查询任务状态。
• 请求重试具备幂等控制，不会重复创建任务。
• 任务失败或超时时能够停止轮询并展示明确错误。

如果请求参数符合限制但持续返回 no_available_account、account_rate_limited 或上游错误，请记录任务 ID、请求时间和错误码后联系 We-AI 技术支持。