The elderly man by the cottage window smiles gently and blinks, warm afternoon light shifting softly across his face, subtle natural movement. Natural sound: a soft breath, distant birdsong through the window, a faint clock tick. Realistic motion, no text, no logos.
Sora 2 Image to Video API
openai/sora-2/image-to-videoSora 2(Image to Video)将静态首帧参考图转化为带原生同步音效的 720p 动态视频,支持 4 至 20 秒固定时长与 16:9 或 9:16 画幅。它能够在严格继承原图主体容貌、服饰纹理与空间布光的同时,赋予画面逼真的物理运动与环境音场。
请先上传一张参考图片,再运行此任务。
生成的视频会显示在这里
填写提示词并添加所需素材,确认设置后点击“运行”。
示例
REST API
快速开始
配置 API Key 与首帧素材,提交图生视频请求,轮询获取 720p 成片。
第一步:配置 API 鉴权
在请求头中携带 Authorization: Bearer <VIDGO_API_KEY> 完成身份验证。
- 任务提交端点
- POST
https://api.vidgo.ai/api/generate/submit - 鉴权请求头
- Authorization: Bearer VIDGO_API_KEY
第二步:提交图生视频任务
向 /api/generate/submit 发起 POST 请求,指定 model 为 openai/sora-2/image-to-video 并传入 prompt 与 image_urls。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "openai/sora-2/image-to-video",
"input": {
"prompt": "The elderly man by the cottage window smiles gently and blinks, warm afternoon light shifting softly across his face, subtle natural movement. Natural sound: a soft breath, distant birdsong through the window, a faint clock tick. Realistic motion, no text, no logos.",
"duration": 4,
"aspect_ratio": "16:9",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/openai/sora-2/image-to-video/v1/01/input.png"
]
}
}
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,失败时读取 data.error_message。
状态查询端点
GET https://api.vidgo.ai/api/generate/status/{task_id}使用 task_id 查询进度;not_started 或 running 时继续轮询,finished 或 failed 时停止。成功后读取 data.files[].file_url,失败时读取 data.error_message。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "task-sora2-i2v-918230",
"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
}
}完整代码示例
展开查看包含鉴权、提交、轮询与终态判断的自动化脚本代码。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "openai/sora-2/image-to-video",
"input": {
"prompt": "The elderly man by the cottage window smiles gently and blinks, warm afternoon light shifting softly across his face, subtle natural movement. Natural sound: a soft breath, distant birdsong through the window, a faint clock tick. Realistic motion, no text, no logos.",
"duration": 4,
"aspect_ratio": "16:9",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/openai/sora-2/image-to-video/v1/01/input.png"
]
}
}
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
done请求参数
向 /api/generate/submit 提交时需在 input 中传递的配置:
| 字段 | 类型 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|---|
| prompt | string | 必填 | — | 动态与动作引导提示词,至少 1 个字符。 |
| image_urls | array | 必填 | — | 包含恰好 1 个图片 URL 的数组,支持 JPEG、PNG 或 WebP,≤10MB。 |
| duration | integer | 可选 | 4 | 视频时长(秒),支持 4, 8, 12, 16, 20。 |
| aspect_ratio | string | 可选 | 16:9 | 画幅比例,支持 16:9 或 9:16。 |
响应字段
提交任务成功后返回的数据结构,以及状态查询接口响应:
| 字段 | 类型 | 描述 |
|---|---|---|
| code | integer | 业务状态码,200 表示成功。 |
| message | string | 业务返回消息或异常描述。 |
| data.task_id | string | 全局唯一的异步任务流水号。 |
| data.status | string | 当前状态:not_started(排队中)、running(生成中)、finished(已完成)、failed(失败)。 |
| data.created_time | string | 任务创建时间(ISO 8601 格式)。 |
| data.files[] | array | 任务生成成功时的文件对象列表。 |
| data.files[].file_url | string | 成片 MP4 视频的下载与播放链接。 |
| data.error_message | string | null | 任务异常终止时的详细错误信息。 |
任务状态流转
依据 data.status 判断任务执行阶段:
not_started任务已被系统受理入队,正等待计算节点分配。
running正在执行图片特征提取、扩散去噪与音效渲染,持续轮询此状态。
finished生成成功,从 data.files[0].file_url 读取成片链接,终止轮询。
failed任务执行异常终止,读取 data.error_message 查看原因并终止轮询。
轮询与重试建议
- 身份认证请求头必须携带 Bearer API Key,若收到 401 请检查密钥有效性。
- 图片校验确保 image_urls 数组包含恰好 1 个可公网访问的图片 URL,图片小于 10MB 且为支持格式。
- 轮询频次建议初始轮询间隔设为 2–3 秒,随着任务持续可逐步放缓,避免高频请求。
- Webhook 回调支持在提交请求顶层配置 callback_url,成片完成后系统将主动推送任务结果。
端点规格
| 规格项 | 取值 | 说明 |
|---|---|---|
| 输入方式 | 文本 + 单张图片 | 通过 prompt 描述动态,image_urls 提供 1 张必填首帧图片。 |
| 输出形式 | MP4 视频(含原生音频) | 异步任务执行完毕后返回成片视频链接。 |
| 可选时长 | 4 / 8 / 12 / 16 / 20 秒 | 默认预设为 4 秒。 |
| 画幅比例 | 16:9 / 9:16 | 默认预设为 16:9。 |
| 原生分辨率 | 720p | 横屏 1280x720,竖屏 720x1280。 |
| 图片格式与大小 | JPEG / PNG / WebP,≤ 10MB | 必须提供恰好 1 个有效的公网访问 URL。 |
| 计费基准 | 按时长阶梯计费 | 4s=48, 8s=96, 12s=144, 16s=192, 20s=240 积分。 |
Sora 2 Image to Video
Sora 2 Image to Video 是 OpenAI 研发的图像生成视频模型。以单张静态参考图作为动作起点,结合文本提示词指导镜头运动与动作演变,直接输出 720p、内嵌原生立体声音轨的连续视频。提供 4、8、12、16 与 20 秒固定档位,是电商商品动效、角色唤醒与创意分镜动态化的主力工具。
为什么选择此端点?
首帧高保真动态唤醒以单张参考图作为绝对视觉基准,精准锁定画面主体外形、空间结构与光影风格,告别空想生成的不确定性。
图像驱动原生音效模型解析首图场景元素与提示词动作,随画面同步生成贴合材质与环境的原生立体声音频,免去二次配音步骤。
运动稳定性与物理规律基于扩散多模态架构,自然演绎衣物摆动、水体流动与人体动力学,动作伸展平滑且避免形态崩解。
预算明确的阶梯时长支持 4s、8s、12s、16s、20s 阶梯计费,任务提交前即可确定积分消耗,便于大批量电商素材与广告生产核算。
横竖屏标准画幅适配支持 16:9 横屏与 9:16 竖屏两种标准规格,完美适配桌面展示、移动端短视频信息流与广告创意规范。
简洁统一的 API 契约在 input 中直接传递公开图片 URL 与描述文本,通过标准异步任务轮询获取最终成片,易于工程化自动化集成。
参数说明
| 参数 | 要求 | 说明 |
|---|---|---|
| prompt | 必填 | 字符串。描述画面动态走向、主体动作细节、运镜方式与声音要素;去除首尾空格后至少包含 1 个字符。 |
| image_urls | 必填 | 字符串数组。包含恰好一张公开可访问的 JPEG、PNG 或 WebP 图片 URL,单图文件大小不超过 10MB。 |
| duration | 可选 | 整数。设置生成视频的时长(秒);可选 4、8、12、16、20,体验区默认预设为 4 秒。 默认值 48121620 |
| aspect_ratio | 可选 | 字符串。设置视频画幅;可选 16:9(默认,1280x720)或 9:16(720x1280)。 默认值 16:99:16 |
使用流程
准备首帧图片与 API Key准备一张主体清晰、曝光适中的 JPEG/PNG/WebP 图片并获取公网 URL,配置请求头 Bearer API Key。
选定时长与画幅根据展示场景选定 4 至 20 秒时长与 16:9 或 9:16 画幅,4 秒成片消耗 48 积分。
提交任务并获取成片向 /api/generate/submit 提交 prompt、image_urls,使用返回的 task_id 轮询直至 finished 读取视频。
计费规则
Sora 2 图生视频采用与文生视频相同的阶梯时长费率:4 秒 48 积分、8 秒 96 积分、12 秒 144 积分、16 秒 192 积分、20 秒 240 积分。成片规格统一为 720p(含原生音频),按 2,000 积分 / 10 美元基准折算,每秒成本约为 0.06 美元,按需扣费无需月费锁定。
| 规格 | 积分 | 说明 |
|---|---|---|
| 4 秒 | 48 积分(约 $0.24) | 默认时长档位,适合快速测试动势与微动作微表情。 |
| 8 秒 | 96 积分(约 $0.48) | 固定时长档位,适合完整的单动作镜头演绎与运镜推拉。 |
| 12 秒 | 144 积分(约 $0.72) | 固定时长档位,适合多阶段连贯动作展示与场景深入。 |
| 16 秒 | 192 积分(约 $0.96) | 固定时长档位,适合慢节奏长镜头与大范围运镜。 |
| 20 秒 | 240 积分(约 $1.20) | 单次最长连续生成档位,适合完整的商业短片成片展示。 |
推荐应用场景
电商商品展示动态化将静态白底商品图或场景穿搭图转化为具备光影流转与物理质感的 720p 动态视频,显著提升商品详情转化率。
数字角色与概念设定唤醒使概念插画与人物肖像动起来,精准维持角色的发色、面容轮廓与服装细节,赋予生动的呼吸微动与肢体语言。
静态摄影画廊与艺术活化将风景摄影与纪实照片赋予生动的自然风声、水流运动与运镜漫游,打造沉浸式数字艺术展览内容。
高频社交短视频广告制作以品牌海报为起点,快速批量派生多条包含同步环境音效的 9:16 竖屏营销视频,大幅削减传统视频制作开销。
创作技巧
- 确保输入的参考图片主体轮廓清晰且光影充足,有助于模型准确提取深度信息并保持连续性。
- 提示词应侧重描述“需要发生的动作”与“镜头运动”,尽量避免与原图已经存在的静态特征发生语义冲突。
- 使参考图的比例尽量贴近请求参数中的 16:9 或 9:16,可获得更协调的画面构图与视角扩展。
- 描述画面动态产生的配套声音(如跑鞋踩在木地板上的摩擦声),能激活更高还原度的原生同步音轨。
使用说明
- image_urls 字段必须传递恰好 1 个公开图片 URL,格式支持 JPEG、PNG、WebP,单张大小限制为 10MB。
- 输出视频格式为 MP4(720p),并内嵌与画面动作同步的原生立体声音频轨道。
- 系统提供 2 秒基准间隔的异步任务轮询机制,支持配置 callback_url 接收自动推送通知。
Sora 2 Image to Video API — 常见问题
Sora 2 Image to Video API 是什么?
Sora 2 Image to Video 是 OpenAI 研发用于图像生成视频的模型。它以单张静态参考图为动作起始点,结合文本提示词直接生成 720p 分辨率、包含动作与环境音效的原生同步视频。基于 OpenAI 的多模态扩散架构,它在严格保留原图主体特征、色彩光影与空间构图的同时,赋予画面逼真的物理动态。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Sora 2 图生视频如何保持原图主体特征一致?
模型深度提取首帧图像中的人脸轮廓、服装纹理与环境构图作为底层约束。建议上传清晰度高、主体明确的高质量素材,并在提示词中聚焦于动作轨迹与运镜指令,避免与原图既有特征相冲突的叙述。
Sora 2 图生视频支持上传几张参考图?
Sora 2 Standard 图生视频端点严格支持输入恰好 1 张首帧参考图片。模型将该图片作为视频的第一帧和主体外观基准向后动态展开,输入数组中包含超过 1 张图片将返回校验错误。
Sora 2 图生视频能为静止图片生成音效吗?
能。模型具有原生音画联合理解机制,能够基于首帧图片中的场景氛围(如森林、雨夜城市、咖啡馆)和提示词动作,自动合成高度匹配的原生环境音与动作音轨,无需后置音频制作。
Sora 2 图生视频单次最长支持多少秒?
单次调用支持生成最长 20 秒视频,提供 4、8、12、16 与 20 秒五档精确时长选择(体验区默认预设为 4 秒)。固定时长让开发者可以在提交前准确预估积分用量并合理安排动态节奏。
Sora 2 图生视频支持哪些图片格式?
支持 JPEG、PNG 和 WebP 等常见图片格式,单张文件大小上限为 10MB。图片需存放于可通过公网直接访问的 HTTP 或 HTTPS 链接上,以便服务端高效拉取解析。
需要自适应画幅与 1080p 时该选哪个端点?
推荐选择 Sora 2 Pro Image to Video 旗舰端点。Pro 旗舰版支持 auto 画幅比例(根据原图指导输出比例),并提供 720p、1024p 和 1080p 超清分辨率选择,适合专业商业交付。