Veo 视频生成 API 文档¶

Veo 官方上游使用统一 /v1/videos 视频任务接口。模型名与上游保持一致，适合需要 Veo 3.1 官方模型名、原生音频、4K、首尾帧和多参考图能力的项目。

接口概览¶

能力	方法	路径	说明
创建任务	`POST`	`/v1/videos`	创建文生视频、图生视频、首尾帧或参考图任务
查询任务	`GET`	`/v1/videos/{task_id}`	查询任务状态和结果
下载文件	`GET`	`/v1/videos/{task_id}/content`	下载完成后的视频文件

所有接口都使用：

Authorization: Bearer $API_KEY

默认 Base URL：

https://agent.tweapi.com

可用模型¶

模型	速度	支持秒数	支持分辨率	支持比例	音频
`veo-3.1-generate-preview`	标准	`4`、`6`、`8`	`720p`、`1080p`、`4k`	`16:9`、`9:16`	原生带音频
`veo-3.1-fast-generate-preview`	更快	`4`、`6`、`8`	`720p`、`1080p`、`4k`	`16:9`、`9:16`	原生带音频

默认模型为 veo-3.1-fast-generate-preview。如果更看重画面稳定性和细节，可以优先测试 veo-3.1-generate-preview；如果更看重出片速度，可以使用 fast 模型。

能力选择¶

images 统一使用数组传入。中继会根据图片数量自动转换为上游推荐的文件输入方式。

图片数量	用途	说明
0 张	文生视频	只根据 `prompt` 生成视频
1 张	首帧图生视频	图片作为视频第一帧
2 张	首尾帧视频	第一张为首帧，第二张为尾帧
3 张	参考图视频	用于保持人物、产品、品牌视觉或场景风格

参考图模式固定使用 3 张图，不要传 negativePrompt，否则请求会被拒绝。

请求参数¶

参数	类型	必填	说明
`model`	string	否	模型名，默认 `veo-3.1-fast-generate-preview`
`prompt`	string	是	视频提示词。画面、动作、镜头、风格、对白、环境音都写在这里
`duration`	number	否	视频秒数：`4`、`6`、`8`，默认 `8`
`resolution`	string	否	分辨率：`720p`、`1080p`、`4k`，默认 `1080p`
`aspectRatio`	string	否	画面比例：`16:9`、`9:16`，默认 `16:9`
`negativePrompt`	string	否	不希望出现的内容，例如 `blurry, watermark, distorted`。参考图模式不要传
`seed`	number	否	随机种子。相同参数下可提高结果可复现性，但不保证完全一致
`images`	string[] / file[]	否	图片数组。JSON 请求传字符串数组；本地文件用 multipart 重复上传 `images`。最多 3 张

JSON 请求中的 images 支持：

输入形式	示例
HTTP(S) 图片 URL	`https://example.com/first-frame.png`
Data URI	`data:image/png;base64,...`
纯 Base64	`iVBORw0KGgo...`

图片格式支持 PNG、JPEG、WebP。URL 图片需要公网可访问。

创建任务¶

curl https://agent.tweapi.com/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "黄昏海边的灯塔，镜头缓慢推进，海浪轻拍礁石，远处有低沉的风声和海鸟声，电影级光影，稳定运镜",
    "duration": 8,
    "resolution": "720p",
    "aspectRatio": "16:9",
    "negativePrompt": "blurry, watermark, distorted, low quality",
    "seed": 20260401
  }'

curl https://agent.tweapi.com/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "让画面中的女孩转头看向镜头，微风吹动头发，背景城市灯光轻微虚化，镜头平稳推进",
    "images": [
      "https://example.com/first-frame.png"
    ],
    "duration": 8,
    "resolution": "720p",
    "aspectRatio": "16:9",
    "seed": 20260401
  }'

curl https://agent.tweapi.com/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "从第一张画面自然过渡到最后一张画面，镜头平稳推进，过渡自然真实",
    "images": [
      "https://example.com/first-frame.png",
      "https://example.com/last-frame.png"
    ],
    "duration": 8,
    "resolution": "720p",
    "aspectRatio": "16:9"
  }'

curl https://agent.tweapi.com/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "参考图片中的产品外观，生成一段电影感广告镜头，镜头平稳推进，背景灯光轻微虚化",
    "images": [
      "https://example.com/ref-1.png",
      "https://example.com/ref-2.png",
      "https://example.com/ref-3.png"
    ],
    "duration": 8,
    "resolution": "720p",
    "aspectRatio": "16:9"
  }'

上传本地图片¶

如果图片在本地，使用 multipart/form-data。文件字段名统一使用 images，按上传文件数量决定用途。

curl https://agent.tweapi.com/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=让画面中的女孩转头看向镜头，微风吹动头发，镜头平稳推进" \
  -F "images=@./first-frame.png;type=image/png" \
  -F "duration=8" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "seed=20260401"

curl https://agent.tweapi.com/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=从首帧自然过渡到尾帧，画面真实稳定" \
  -F "images=@./first-frame.png;type=image/png" \
  -F "images=@./last-frame.png;type=image/png" \
  -F "duration=8" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9"

curl https://agent.tweapi.com/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=参考图片中的产品外观，生成一段电影感广告镜头" \
  -F "images=@./ref-1.png;type=image/png" \
  -F "images=@./ref-2.png;type=image/png" \
  -F "images=@./ref-3.png;type=image/png" \
  -F "duration=8" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9"

创建响应¶

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "queued",
  "model": "veo-3.1-generate-preview",
  "created_at": 1775025000
}

字段	说明
`id`	任务 ID，用于后续查询和下载
`status`	初始状态，通常为 `queued`
`model`	实际使用的模型
`created_at`	创建时间戳，单位秒

查询任务¶

curl https://agent.tweapi.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -H "Authorization: Bearer $API_KEY"

状态说明¶

status	说明
`queued`	已排队
`processing`	生成中
`completed`	已完成，可以读取结果 URL 或下载文件
`failed`	生成失败，查看 `error.message`

完成响应¶

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "completed",
  "progress": 100,
  "model": "veo-3.1-generate-preview",
  "video_url": "https://agent.tweapi.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content",
  "created_at": 1775025000,
  "completed_at": 1775025090
}

下载视频¶

优先使用查询响应里的 video_url。如果需要通过任务 ID 下载文件，可以使用：

curl https://agent.tweapi.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content \
  -H "Authorization: Bearer $API_KEY" \
  --output veo-output.mp4

Python 轮询示例¶

import time
import requests

API_BASE = "https://agent.tweapi.com"
API_KEY = "sk-xxx"

task = requests.post(
    f"{API_BASE}/v1/videos",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "veo-3.1-fast-generate-preview",
        "prompt": "黄昏海边的灯塔，镜头缓慢推进，海浪轻拍礁石，电影级光影，带环境音",
        "duration": 8,
        "resolution": "720p",
        "aspectRatio": "16:9",
    },
    timeout=60,
).json()

task_id = task["id"]

while True:
    result = requests.get(
        f"{API_BASE}/v1/videos/{task_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=60,
    ).json()

    if result["status"] == "completed":
        print(result.get("video_url") or result.get("data", [{}])[0].get("url"))
        break

    if result["status"] == "failed":
        raise RuntimeError(result.get("error", {}).get("message", "生成失败"))

    time.sleep(3)

注意事项¶

场景	建议
需要音频	将对白、环境音、音效写进 `prompt`
需要排除内容	文生视频、首帧和首尾帧可以传 `negativePrompt`
参考图模式	固定传 3 张图，不传 `negativePrompt`
需要竖屏	设置 `aspectRatio` 为 `9:16`
需要更清晰	设置 `resolution` 为 `1080p` 或 `4k`，生成耗时和成本通常也会提高
首尾帧 / 参考图	`duration` 必须为 `8`，传 `4` 或 `6` 会被拒绝