xgapi Veo 3.1 视频对接教程

本文说明如何通过 xgapi（OpenAI 兼容视频接口）调用：

模型 ID	说明	文生视频	首帧图生	首尾帧	参考图（≤3）
`veo-3.1-generate-preview`	普通版	✅	✅	✅	✅（仅 16:9）
`veo-3.1-fast-generate-preview`	Fast 版	✅	✅	✅	❌

1. 接入信息

项	值
API 基础地址	`https://api.xgapi.top`（以你实际站点为准）
鉴权	`Authorization: Bearer <你的 xgapi 令牌>`
协议	异步：提交拿 `task_id` → 轮询查结果

2. 接口一览

用途	方法	路径
提交视频任务	`POST`	`/v1/videos`
查询任务状态	`GET`	`/v1/videos/{task_id}`
下载成片（可选）	`GET`	`/v1/videos/{task_id}/content`

建议每 5～10 秒轮询一次；成片通常需数十秒到数分钟。请勿高频轮询。

3. 公共参数

3.1 顶层字段

参数	类型	必填	说明
`model`	string	✅	`veo-3.1-generate-preview` 或 `veo-3.1-fast-generate-preview`
`prompt`	string	✅	视频描述（建议含主体、动作、场景、镜头、声音）
`seconds`	string	❌	时长秒数：`"4"` / `"6"` / `"8"`，默认 `"8"`
`duration`	number	❌	时长秒数（整数）；与 `seconds` 同时存在时以 `seconds` 为准
`size`	string	❌	尺寸快捷写法，用于推断分辨率与比例，如 `1280x720`、`720x1280`
`input_reference`	string	❌	首帧图：公网 URL / data URI / 纯 Base64
`image`	string	❌	单张图，语义同首帧
`images`	string[]	❌	单张 = 首帧；多张或 `metadata.mode=reference` = 参考图模式
`metadata`	object	❌	扩展参数，见下表

3.2 `metadata` 常用字段

参数	类型	说明
`resolution`	string	`720p` / `1080p`，默认 `720p`
`aspectRatio` / `aspect_ratio`	string	`16:9` / `9:16`，默认 `16:9`
`last_frame` / `last_frame_url`	string	尾帧图 URL 或 data URI（必须同时有首帧）
`mode`	string	传 `reference` 时，`images` 按参考图解析
`referenceImages` / `reference_images`	array	显式参考图列表（1～3）
`referenceType` / `reference_type`	string	参考类型，默认 `asset`
`negativePrompt` / `negative_prompt`	string	负向提示（参考图模式不建议使用）

3.3 `size` 推断规则

`size` 示例	→ resolution	→ aspectRatio
`1280x720` / `720p`	`720p`	`16:9`
`720x1280`	`720p`	`9:16`
`1920x1080` / `1080p`	`1080p`	`16:9`
`1080x1920`	`1080p`	`9:16`
未传	`720p`	`16:9`

显式写 metadata.resolution / metadata.aspectRatio 时，优先于 size。

3.4 图片说明

支持：公网 http(s) URL、data URI、multipart 文件、纯 Base64。

URL 需公网可直接下载（返回 200），不能依赖登录态或内网地址。

3.5 模式判定

模式	判定条件	限制
文生视频	无图	时长 4/6/8；比例 16:9 或 9:16
首帧图生	有 1 张首帧，无尾帧、非参考图模式	同上
首尾帧	有首帧 + 尾帧	时长强制 8；比例 16:9 或 9:16
参考图	`mode=reference` / `referenceImages` / `images` 多张	仅普通版；时长强制 8；比例强制 16:9；1～3 张

互斥：参考图不可与首帧/尾帧同时使用。Fast 版不支持参考图。

4. 提交与查询

4.1 提交成功响应

{
  "id": "task_xxxxxxxx",
  "task_id": "task_xxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1785412796
}

请保存 id（或 task_id）用于轮询。

4.2 查询中 / 成功 / 失败

处理中：

{
  "id": "task_xxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "in_progress",
  "progress": 50
}

成功：

{
  "id": "task_xxxxxxxx",
  "task_id": "task_xxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1785412796,
  "completed_at": 1785412863,
  "metadata": {
    "url": "https://example.com/result.mp4"
  }
}

成片直链取 metadata.url；也可再请求 GET /v1/videos/{task_id}/content 下载。链接可能有时效，请及时转存。

失败：

{
  "id": "task_xxxxxxxx",
  "status": "failed",
  "progress": 100,
  "error": {
    "message": "...",
    "code": "failed"
  }
}

status 常见值：queued / in_progress / completed / failed（首轮偶发 unknown，继续轮询即可）。

5. 场景示例

以下将 {BASE} 换为你的站点根（如 https://api.xgapi.top），{KEY} 换为 xgapi 令牌。

5.1 文生视频

显式分辨率 / 竖屏：

{
  "model": "veo-3.1-generate-preview",
  "prompt": "海岸灯塔黄昏，镜头缓慢推进",
  "seconds": "6",
  "metadata": {
    "resolution": "1080p",
    "aspectRatio": "9:16"
  }
}

5.2 首帧图生视频

等价写法："image": "https://..." 或 "images": ["https://..."]。

multipart 上传本地文件：

5.3 首尾帧

{
  "model": "veo-3.1-generate-preview",
  "prompt": "镜头平滑推进，主体从首帧姿势自然过渡到尾帧姿势",
  "seconds": "8",
  "input_reference": "https://cdn.example.com/start.jpg",
  "metadata": {
    "last_frame": "https://cdn.example.com/end.jpg",
    "resolution": "1080p",
    "aspectRatio": "16:9"
  }
}

注意：只传尾帧不传首帧会返回 400；时长会按上游要求使用 8 秒。

5.4 参考图引导（仅普通版）

{
  "model": "veo-3.1-generate-preview",
  "prompt": "保持参考图中的角色外观一致。角色缓慢向前迈步并摆出防御姿态，电影感灯光",
  "seconds": "8",
  "images": [
    "https://cdn.example.com/ref1.jpg",
    "https://cdn.example.com/ref2.jpg"
  ],
  "metadata": {
    "mode": "reference",
    "resolution": "720p",
    "aspectRatio": "16:9",
    "referenceType": "asset"
  }
}

或显式 referenceImages：

{
  "model": "veo-3.1-generate-preview",
  "prompt": "保持参考图角色外观一致……",
  "seconds": "8",
  "metadata": {
    "aspectRatio": "16:9",
    "resolution": "720p",
    "referenceImages": [
      { "url": "https://cdn.example.com/ref1.jpg", "referenceType": "asset" },
      { "url": "https://cdn.example.com/ref2.jpg" }
    ]
  }
}

限制回顾：Fast 版不可用；最多 3 张；必须 16:9；不可与首/尾帧混用。

5.5 轮询直到完成

6. 端到端最小流程（文生）

7. 常见错误

现象	原因	处理
`model_not_found` / 无可用渠道	模型未挂渠道或分组不匹配	检查后台渠道模型与令牌分组
`durationSeconds must be 4, 6 or 8`	时长不合法	只传 4 / 6 / 8
`resolution must be 720p or 1080p`	分辨率不支持	改用 720p / 1080p
`last_frame requires a first frame`	只传了尾帧	补 `input_reference` / `image`
`referenceImages is not supported on fast model`	Fast 版传了参考图	改用普通版或去掉参考图
`referenceImages mode only supports aspectRatio 16:9`	参考图用了竖屏	改为 `16:9`
`download image failed` / 素材不可访问	图片 URL 境外/本站拉不到	换公网稳定图床或 multipart 上传
一直 `queued` / `in_progress`	生成中	继续轮询，建议最长等待 10～15 分钟

8. 能力对照速查

能力	普通版	Fast 版
文生视频	✅	✅
首帧图生	✅	✅
首尾帧	✅（时长 8）	✅（时长 8）
参考图 1～3	✅（16:9、时长 8）	❌
视频延长 / remix	❌	❌

Veo 3.1 视频对接教程

xgapi Veo 3.1 视频对接教程#

1. 接入信息#

2. 接口一览#

3. 公共参数#

3.1 顶层字段#

3.2 metadata 常用字段#

3.3 size 推断规则#

3.4 图片说明#

3.5 模式判定#

4. 提交与查询#

4.1 提交成功响应#

4.2 查询中 / 成功 / 失败#

5. 场景示例#

5.1 文生视频#

5.2 首帧图生视频#

5.3 首尾帧#

5.4 参考图引导（仅普通版）#

5.5 轮询直到完成#

6. 端到端最小流程（文生）#

7. 常见错误#

8. 能力对照速查#