跳转到内容
HiAPI Docs
HiAPI
在线试用 获取 API Key
中文
English 中文

Veo 3.1 Text to Video API

POST /v1/tasks

所有模型都通过 统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型名称 veo-3.1/text-to-video
类型 视频生成（文生视频）
接口 POST /v1/tasks
价格 见 HiAPI 定价

Google Veo 3.1 旗舰文生视频 API，电影级画质与原生音频，最高 4K 分辨率，生成 4 / 6 / 8 秒视频片段，适合广告级短片与高要求内容创作。

生产建议

生产环境建议
  • 生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
  • GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
  • callback.when 当前建议固定为 final；success 和 fail 都可能触发终态通知，你的服务端需要按 taskId 做幂等处理。

适用场景

电影级成片

Veo 3.1 旗舰档在画质、运动真实感和光影一致性上都是第一梯队，适合广告片、品牌片和高要求叙事镜头。

promptresolution
带原生音频的叙事短片

一次生成画面与原生音频（环境音/音效/配乐），音画同步，省去后期配音。

generate_audio
4K 高清交付

支持 720p / 1080p / 4K，按需选清晰度，满足高分辨率投放与大屏展示。

resolutionduration
横竖屏适配

16:9 与 9:16 用同一套提示词适配信息流横屏和竖屏短视频。

aspect_ratio

请求参数

model string 必填

固定填 veo-3.1/text-to-video。

示例 veo-3.1/text-to-video
input object 必填

业务参数对象；Veo 3.1 Text to Video 的模型专属配置都放在这里。

prompt string 必填

描述要生成视频内容的文本提示词。

aspect_ratio enum 可选

输出视频画幅比例。

默认 16:9 可选值: 16:99:16
resolution enum 必填

输出视频分辨率，分辨率越高单价越高。

默认 720p 可选值: 720p1080p4k
duration enum 必填

视频时长（秒），费用按时长计算。

默认 8 可选值: 468
generate_audio boolean 可选

是否生成原生音频音轨，开启后单价更高。

默认 true
negative_prompt string 可选

描述要在生成视频中避免出现的内容。

seed integer 可选

随机种子，用于复现相同结果。

callback object 可选

可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。

url string 必填

传入 callback 时必填；接收任务终态通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback
when enum 可选

回调触发时机；当前建议固定为 final。

默认 final 可选值: final

用例示例

4K 含音电影感成片

4K / 8 秒、原生音频，展示旗舰档的画质与音画同步。

请求体
{
  "model": "veo-3.1/text-to-video",
  "input": {
    "prompt": "冲浪者穿越巨大的绿松石管浪，阳光从浪尖迸射，管内跟踪镜头，海浪轰鸣",
    "aspect_ratio": "16:9",
    "resolution": "4k",
    "duration": 8,
    "generate_audio": true
  }
}
1080p 氛围叙事镜头

1080p / 8 秒、含音，适合叙事感和音乐氛围强的镜头。

请求体
{
  "model": "veo-3.1/text-to-video",
  "input": {
    "prompt": "昏暗爵士酒吧里萨克斯手在琥珀色聚光灯下独奏，雨滴打在窗上，霓虹微光",
    "aspect_ratio": "16:9",
    "resolution": "1080p",
    "duration": 8,
    "generate_audio": true
  }
}
720p 无音低成本出片

720p / 4 秒、关闭音频，验证创意时的最低成本档。

请求体
{
  "model": "veo-3.1/text-to-video",
  "input": {
    "prompt": "雨滴沿夜晚的玻璃窗滑落，窗外霓虹光斑变幻，微距静止镜头",
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "duration": 4,
    "generate_audio": false
  }
}

获取结果

  1. 提交成功后立即返回 taskId（不等待生成完成）。
  2. 生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
  3. status=success 后，从返回的 output[].url 下载生成的视频。
  4. 如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

Veo 3.1 和 Veo 3.1 Fast 有什么区别？

veo-3.1 是旗舰画质档，画面细节、运动真实感和音频质量更好，单价更高；veo-3.1-fast 生成更快、单价更低。两者参数相同（720p/1080p/4K、4/6/8 秒、原生音频），可按质量与成本需求切换。

支持哪些分辨率和时长？

分辨率支持 720p / 1080p / 4K，时长支持 4 / 6 / 8 秒。价格按分辨率、是否含音和时长（按秒）组合计费，4K 与开启音频单价更高，实时价格见价格页。 查看价格

generate_audio 怎么影响价格？

开启原生音频（generate_audio=true，默认开启）单价更高；画面不需要声音时设为 false 可明显降本。每秒单价以价格页为准。 查看价格

怎么拿到生成的视频？

提交后立即返回 taskId，任务进入终态后从 output[].url 下载视频。生产环境建议在请求体顶层传 callback.url 收终态通知，减少无效轮询。

下一步