Vidu 视频接口概览

通过 ModelSell 调用 Vidu Q2、Q3 视频模型，了解原生协议、统一视频格式、任务查询及 Q4 Preview 的支持边界。

Vidu 视频采用异步任务流程：创建任务、保存返回的任务 ID、查询状态，成功后下载视频。本系列参考 Vidu Q4 Preview 图生视频官方文档，并按 ModelSell 当前开放的模型与接口说明接入方法。

模型与可用操作

模型名称	当前可用操作
`viduq2`	文生视频、参考生视频
`viduq2-pro`	图生视频、首尾帧视频、参考生视频
`viduq2-turbo`	图生视频、首尾帧视频
`viduq2-pro-fast`	图生视频、首尾帧视频
`viduq3-pro`	文生视频、图生视频、首尾帧视频
`viduq3-turbo`	文生视频、图生视频、首尾帧视频

以上六款 Q2 / Q3 模型已完成生成及计费验证。请求使用表中的准确模型名，并确保 API Key 所属分组及模型权限允许调用。Q3 Turbo 的官方参考生视频能力不代表当前渠道已开放该操作。

viduq4-preview 已有协议适配，本系列提供其参数说明与条件示例；当前未确认有可用的生产渠道。仅在模型目录、权限及渠道均已开放后调用，不能据此页面判断 Q4 已上线。

地址与鉴权

export MODELSELL_BASE_URL="https://api.modelsell.com"
export MODELSELL_API_KEY="<your-modelsell-api-key>"

所有请求发往 ModelSell，使用 Authorization: Bearer $MODELSELL_API_KEY。创建请求的 Content-Type 为 application/json，请求超时建议至少 300 秒。自定义接入域名时只替换 MODELSELL_BASE_URL。

官方文档中的 api.vidu.cn 与 Authorization: Token ... 用于直接访问 Vidu；通过 ModelSell 接入时使用上述地址和 Bearer 鉴权。

选择接口格式

格式 / 操作	创建路径	查询路径
原生文生视频	`POST /ent/v2/text2video`	`GET /ent/v2/tasks/{task_id}/creations`
原生图生视频	`POST /ent/v2/img2video`	同上
原生首尾帧视频	`POST /ent/v2/start-end2video`	同上
原生参考生视频	`POST /ent/v2/reference2video`	同上
统一视频格式	`POST /v1/videos` 或 `POST /v1/video/generations`	`GET /v1/videos/{task_id}`

原生格式适合直接迁移官方请求或使用完整的模型参数；统一视频格式适合复用 model、prompt、images、seconds、size 等公共字段。

创建返回的 task_… 是 ModelSell 公共任务 ID。后续查询始终使用创建响应中的真实 ID，并沿用创建时的 ModelSell API Key。不要用官方示例 ID、上游 ID 或回调中的 ID 替换它。

创建 Q3 文生视频

curl --max-time 300 "$MODELSELL_BASE_URL/ent/v2/text2video" \
  -H "Authorization: Bearer $MODELSELL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "viduq3-turbo",
    "prompt": "晨光照进房间，一只红色陶瓷茶壶放在木桌上，镜头缓慢推进",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "audio": false,
    "is_rec": false,
    "watermark": false,
    "seed": 0
  }'

创建响应示例（具体字段可能随模型变化）：

{
  "task_id": "task_example_vidu",
  "state": "created",
  "model": "viduq3-turbo"
}

查询任务与读取视频

保存真实 task_id，每 10–15 秒查询一次：

export TASK_ID="<returned-task-id>"
curl --max-time 300 "$MODELSELL_BASE_URL/ent/v2/tasks/$TASK_ID/creations" \
  -H "Authorization: Bearer $MODELSELL_API_KEY"

原生 `state`	含义
`created`、`queueing`、`processing`	尚未完成，继续轮询
`success`	成功，读取 `creations[].url`
`failed`	失败，保存 `err_code` 排查

原生查询返回的公共任务 ID 位于顶层 id，创建响应则使用 task_id。成功结果结构如下：

{
  "id": "task_example_vidu",
  "state": "success",
  "err_code": "",
  "credits": 35,
  "creations": [{
    "id": "creation_example",
    "url": "https://example.com/generated-video.mp4",
    "cover_url": "https://example.com/cover.jpg",
    "watermarked_url": "https://example.com/watermarked-video.mp4"
  }]
}

示例中的积分和地址仅用于展示结构。视频、封面及带水印结果地址按官方说明有效期为 24 小时，请及时下载或转存。Python 轮询与下载提供完整示例。

计费与错误处理

创建时预扣，成功后按任务积分及对应模型价格结算，失败按任务流程退款；查询不重复收费。credits 是 Vidu 积分，不能直接当作美元金额或 token 数量。具体价格以 ModelSell Vidu 模型定价及所用分组为准。

当前渠道使用即时生成，拒绝 off_peak: true；Q3 暂不开放 is_rec: true 的提示词扩写，请提供明确提示词并传 is_rec: false。原生接口保留 false、0 等显式值。

HTTP 请求失败时保存状态码、错误正文及请求标识；创建请求超时后先确认是否已受理，避免直接重试造成重复任务。轮询超时只结束客户端等待，不能视作任务取消或退款。本系列提供创建与查询接口；任务列表、取消、删除和账户余额接口未开放。

callback_url 由上游直接发送通知，可能携带上游任务 ID；客户端仍应以 ModelSell 创建响应中的公共 ID 查询确认结果。