A rhinoceros hornbill glides low over a misty rainforest canopy at dawn, the camera tracking alongside at wing height, golden light breaking through drifting fog, droplets scattering from its wingtips as it banks between emergent trees. Natural sound: slow powerful wingbeats, distant gibbon calls, insects waking, a soft rush of humid air. Realistic wildlife documentary motion, no text, no logos.
Veo 3.1 Official Text-to-Video API
google/veo3.1/text-to-videoGoogle Veo 3.1 官方旗舰文生视频模型,将文本构想转化为具备电影级物理质感与多轴运镜的 4K 视频。支持精准自然语言镜头控制与动作对齐的原生音效,按秒灵活计费,直连 Vidgo API。
生成的视频会显示在这里
填写提示词并添加所需素材,确认设置后点击“运行”。
示例
REST API
快速开始
完成 API 认证,提交素材与生成指令,再通过任务 ID 获取视频结果。
连接 Vidgo API
创建 API Key,仅保存在服务端,并发送 Authorization: Bearer VIDGO_API_KEY。
- 接口
- POST
https://api.vidgo.ai/api/generate/submit - 认证
- Authorization: Bearer VIDGO_API_KEY
提交一次生成任务
按请求示例填写当前端点的素材与设置,提交后保存 task_id,用于后续查询生成进度和结果。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "google/veo3.1/text-to-video",
"input": {
"prompt": "A rhinoceros hornbill glides low over a misty rainforest canopy at dawn, the camera tracking alongside at wing height, golden light breaking through drifting fog, droplets scattering from its wingtips as it banks between emergent trees. Natural sound: slow powerful wingbeats, distant gibbon calls, insects waking, a soft rush of humid air. Realistic wildlife documentary motion, no text, no logos.",
"duration": 8,
"aspect_ratio": "16:9",
"sound": true,
"resolution": "720p"
}
}
JSON
)
RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
printf 'API error: %s
' "$RESPONSE" >&2
exit 1
fi
printf '%s
' "$RESPONSE"等待结果
用 task_id 查询,not_started/running 继续,finished/failed 停止。成功后读取 data.files[].file_url。
查询状态
GET https://api.vidgo.ai/api/generate/status/{task_id}以 2 秒为基准间隔轮询状态,长时间任务可适当拉长间隔。仅在 not_started 或 running 时继续,遇到 finished 或 failed 立即停止。也可以在同一请求中配置 callback_url 接收回调通知。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "running",
"created_time": "2026-09-17T10:00:00Z"
}
}{
"code": 200,
"data": {
"task_id": "task-unified-...",
"status": "finished",
"files": [
{
"file_url": "https://storage.vidgo.ai/generated/video.mp4",
"file_type": "video"
}
],
"created_time": "2026-08-22T10:00:00Z",
"progress": 100,
"error_message": null
}
}完整可运行示例
展开后可查看包含 HTTP 与业务码检查、task_id 校验、轮询、终态处理和超时边界的完整脚本。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "google/veo3.1/text-to-video",
"input": {
"prompt": "A rhinoceros hornbill glides low over a misty rainforest canopy at dawn, the camera tracking alongside at wing height, golden light breaking through drifting fog, droplets scattering from its wingtips as it banks between emergent trees. Natural sound: slow powerful wingbeats, distant gibbon calls, insects waking, a soft rush of humid air. Realistic wildlife documentary motion, no text, no logos.",
"duration": 8,
"aspect_ratio": "16:9",
"sound": true,
"resolution": "720p"
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
printf 'Timed out after 600 seconds
' >&2
exit 1
fi
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
exit 1
fi
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep "$POLL_DELAY"
if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
doneinput 参数
下表列出 input 对象的可用参数、类型与默认值;请求示例同时展示顶层必填字段 model。按当前任务准备素材并配置输出。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| prompt | string | 是 | — | 去除首尾空格后为 1–1,000 个字符。 |
| duration | integer | 否 | 8 | 4、6 或 8,单位为秒。 |
| aspect_ratio | string | 否 | 16:9 | 16:9 或 9:16。 |
| resolution | string | 否 | 720p | 720p / 1080p / 4k。 |
| sound | boolean | 否 | true | true 生成原生音频;false 返回静音片段。 |
响应字段
提交成功后返回任务 ID;状态查询提供任务进度、输出文件,以及任务失败时的错误详情。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 业务结果码;成功响应使用 0 或 200。 |
| message | string | 可读说明或错误详情。 |
| data.task_id | string | 用于状态查询路径的任务 ID。 |
| data.status | string | not_started、running、finished 或 failed。 |
| data.created_time | string | 任务创建时间,date-time 格式。 |
| data.progress | integer | 任务进度,范围为 0–100;仅在响应包含此字段时提供。 |
| data.files[] | array | 成功任务的全部输出文件,按响应顺序返回。 |
| data.files[].file_url | string | 生成视频的公开 URL。 |
| data.files[].file_type | string | 文件类型,例如 video。 |
| data.error_message | string | null | 状态为 failed 时的失败详情。 |
任务生命周期
在 not_started 或 running 状态下继续查询;收到 finished 或 failed 后结束轮询,并分别处理输出文件或错误详情。
not_started任务已接受,等待开始。
running正在生成。继续使用同一 task_id 轮询。
finished生成成功。从 data.files[].file_url 读取视频地址。
failed生成失败。读取 data.error_message 并停止轮询。
轮询与错误
- 认证收到 401 时,检查 Authorization 中的 Bearer API Key,更新凭据后重试。
- 校验收到 400 时,依据响应说明核对必填素材、参数取值与可用积分,完成相应调整后重新提交。
- 网络与超时状态查询遇到网络错误或超时时,保留原 task_id 并重试查询,再根据返回的任务状态处理结果。
- 轮询间隔以 2 秒为基准间隔发起状态查询;如任务耗时较长,可逐步增加查询间隔。
- 终态仅在 not_started 或 running 时继续。遇到 finished 或 failed 立即停止。
- 回调选项可在请求顶层提供 callback_url 接收终态任务对象;投递失败时仍可轮询。
模型规格
| 规格 | 取值 | 说明 |
|---|---|---|
| 输入模式 | 纯文本 | 提示词用于描述场景、运镜、光线、情绪和声音。 |
| 输出 | 可选原生音频的视频 | 提交后返回异步任务 ID;完成后包含视频文件。 |
| 分辨率 | 720p / 1080p / 4k | 默认 720p。 |
| 时长 | 4 / 6 / 8 秒 | 默认 8 秒。 |
| 画面比例 | 16:9 / 9:16 | 默认 16:9。 |
| 计费依据 | 按秒计费 | 720p 无音频 24 积分/秒; 带音频 48 积分/秒. 1080p 无音频 24 积分/秒; 带音频 48 积分/秒. 4k 无音频 48 积分/秒; 带音频 72 积分/秒. |
Veo 3.1 Official Text-to-Video
Google Veo 3.1 官方旗舰文生视频模型,将文本构想转化为具备电影级物理质感与多轴运镜的 4K 视频。支持精准自然语言镜头控制与动作对齐的原生音效,按秒灵活计费,直连 Vidgo API。
为什么选择此端点?
官方 Google 模型系列使用包含 Lite、Fast 和 Quality 变体的官方 Veo 3.1 系列,无需为每种工作流单独对接。
透明的按秒计价提交前用时长乘以所选模型、分辨率和音频费率,即可预估每笔任务费用。
音频成本控制按请求开关原生音频,让预览更便宜,成片再加入更丰富的声音。
4K 升级路径先用较低成本完成草稿,确认高分辨率值得额外积分后再升级到 Fast 或 Quality 的 4K 任务。
便于接入的异步 API一次提交即可获得任务 ID,再通过轮询或回调在生产系统中收取结果。
参数
| 参数 | 要求 | 说明 |
|---|---|---|
| prompt | 必填 | 字符串。描述场景、动作、运镜、光线和声音;去除首尾空格后为 1–1,000 个字符。 |
| duration | 可选 | 整数。设置输出时长;体验区默认预选 8 秒。 默认 846 |
| aspect_ratio | 可选 | 字符串。控制画面比例;体验区默认预选 16:9。 默认 16:99:16 |
| resolution | 可选 | 字符串。设置输出分辨率;体验区默认预选 720p。 默认 720p1080p4k |
| sound | 可选 | 布尔值。是否生成原生音频;体验区默认预选 true。 默认 truefalse |
如何使用
描述场景与动作先写清主体、环境和主要动作,再在同一条提示词中补充运镜与声音。
设置时长、画面比例、分辨率和音频选择 4、6 或 8 秒,16:9 或 9:16 画幅、当前端点支持的分辨率,以及是否包含原生音频。
确认费用并运行查看运行按钮显示的当前按秒费用,完成必填提示词和素材上传后点击“运行”。
预览并下载视频任务完成后,在输出面板预览视频,再点击“下载视频”保存结果。
价格
Veo 3.1 Official 按生成秒数计费。最终费用 = 时长 × 所选每秒费率。美元换算采用当前基础 API 计费:2,000 积分 = $10。示例:Quality 8 秒 720p 带音频任务为 8 × 48 = 384 积分,按基础 API 积分汇率约 $1.92。
| 用量 | 费率 | 说明 |
|---|---|---|
| 720p,无音频 | 24 积分/秒($0.12/秒) | 8 秒 = 192 积分($0.96)。 |
| 720p,带音频 | 48 积分/秒($0.24/秒) | 默认 720p / 8 秒带音频为 384 积分($1.92)。 |
| 1080p,无音频 | 24 积分/秒($0.12/秒) | 8 秒 = 192 积分($0.96)。 |
| 1080p,带音频 | 48 积分/秒($0.24/秒) | 8 秒 = 384 积分($1.92)。 |
| 4k,无音频 | 48 积分/秒($0.24/秒) | 8 秒 = 384 积分($1.92)。 |
| 4k,带音频 | 72 积分/秒($0.36/秒) | 8 秒 = 576 积分($2.88)。 |
适用场景
AI 视频应用通过同一套异步 API,为需要文本、图片、首尾帧、音频和支持分辨率控制的应用接入官方 Google Veo 3.1。
营销团队生成广告概念、产品镜头、发布短片和活动变体,并按预算与评审阶段选择 Lite、Fast 或 Quality。
大规模试错先用较低成本的 Lite 做草稿,确认更高保真度值得额外花费后再把最佳提示词组合升级到 Fast 或 Quality。
创作者平台为创作者提供带清晰计价、原生音频、横竖画幅和简单异步结果处理的 Google 视频能力。
专业建议
- 提交前用时长乘以所选分辨率和音频费率,即可预估每笔任务费用。
- 按请求开关原生音频,让预览更便宜,成片再加入更丰富的声音。
- 提示词控制在 1,000 个字符以内,并将运镜与主体动作分开描述。
- 低成本迭代用 Lite,均衡量产用 Fast,当画质比最低成本更重要时用 Quality。
使用说明
- Veo 3.1 Official Text-to-Video 使用必填文本提示词生成视频,并可通过时长、分辨率、画面比例和音频设置配置输出。
- 提示词上限为 1,000 个字符。时长支持 4、6 或 8 秒。
- 通过 sound 参数请求带音频或静音输出。带音频与无音频任务使用不同的按秒费率。
- Fast 和 Quality Official 支持 720p、1080p 和 4K。
- 此端点仅支持文本。如需首帧或首尾帧任务,请使用 Official Image-to-Video 页面。
- 通过 API 提交后保存 task_id,用于查询任务进度和获取生成结果。
相关模型
Veo 3.1 Official Text-to-Video API 常见问题
Veo 3.1 Official Text-to-Video API 是什么?
Veo 3.1 Official Text-to-Video 让开发者通过 Vidgo API 调用官方 Google Veo 3.1 模型系列。本页是 Veo 3.1 Official 的文生视频端点。
应该使用哪个 model ID?
在 model 字段使用 google/veo3.1/text-to-video。不要提交包含 -official 的页面路径。
Veo 3.1 Official 支持音频吗?
支持。通过 sound 参数请求带音频或静音输出。带音频与无音频任务使用不同的按秒费率。
支持哪些图片输入模式?
此文生视频端点不接受图片。如需一张首帧或两张首尾帧图片,请使用对应的 Official Image-to-Video 页面。
接入前需要了解哪些限制?
提示词上限为 1000 个字符。时长支持 4、6 或 8 秒。Fast 和 Quality Official 支持 720p、1080p 和 4K。
异步交付如何工作?
向 generate 接口提交任务并获得 task_id。后端可用 task_id 轮询状态,或在请求中带上 callback_url 异步接收结果。
什么时候该选 Lite、Fast 或 Quality?
需要低成本迭代时选 Lite,需要均衡产能和 4K 时选 Fast,需要最高画质或旗舰 4K 结果时选 Quality。
什么情况下不适合选择 Veo 3.1 Official?
如果单次请求需要超过 8 秒,或需要三图参考工作流,则不太适合。