视视频接口API

gpt-image-2 接口文档(/v1/videos 视频接口格式)

接口地址

POST/v1/videos

功能说明

通过 /v1/videos 接口调用 GPT 图片生成能力(与视频生成共用接口,通过 model 参数区分),支持文生图和图生图两种模式,采用异步任务方式,先提交返回任务 ID,再轮询获取结果。

画幅 / 宽高比:支持三种控制方式:

  1. aspect_ratio 传入固定比例字符串(如 9:16、16:9 等),精确控制输出比例
  2. size 传入像素尺寸字符串(如 "1280x720"、"1456x624")——与 aspect_ratio 二选一,不需要同时传
  3. 传 "auto",或两个参数均不传——两者等价,均根据提示词内容自动推断,无固定比例;提示词中若写明了比例(如"竖屏 9:16"),模型也会据此生成

分辨率档位(见下文「分辨率控制」):

  • 分辨率固定:gpt-image-2 为 1K,gpt-image-2-2K 为 2K,gpt-image-2-4K 为 4K,gpt-image-2.5 为 1K(不要传 2K / 4K)。换分辨率要换 model
  • 可用参数选档:gpt-image-2-medium、gpt-image-2-vip、gpt-image-2.5-flare / sunburst 及其 -vip、gpt-image-2.6-flare / sunburst 及其 -vip。同一模型出 1K / 2K / 4K,用 size 像素,或 aspect_ratio + image_size / resolution

质量:非 -vip 固定 medium,可不传 quality。-vip 可传 low / medium / high,不传则自动判断。见下文「质量」。

支持的模型

model 参数分辨率质量说明
gpt-image-21K固定 medium分辨率固定 1K
gpt-image-2-2K2K固定 medium分辨率固定 2K
gpt-image-2-4K4K固定 medium分辨率固定 4K
gpt-image-2-medium1K / 2K / 4K固定 medium用参数选分辨率
gpt-image-2-vip1K / 2K / 4Klow / medium / high用参数选分辨率;不传 quality 则自动判断
gpt-image-2.5仅 1K固定 medium分辨率固定 1K,不要传 2K / 4K
gpt-image-2.5-flare1K / 2K / 4K固定 medium用参数选分辨率
gpt-image-2.5-sunburst1K / 2K / 4K固定 medium调用方式与 gpt-image-2.5-flare 相同
gpt-image-2.5-flare-vip1K / 2K / 4Klow / medium / high调用方式与 gpt-image-2.5-flare 相同;不传 quality 则自动判断
gpt-image-2.5-sunburst-vip1K / 2K / 4Klow / medium / high调用方式与 gpt-image-2.5-flare-vip 相同
gpt-image-2.6-flare1K / 2K / 4K固定 medium调用方式与 gpt-image-2.5-flare 相同
gpt-image-2.6-sunburst1K / 2K / 4K固定 medium调用方式与 gpt-image-2.6-flare 相同
gpt-image-2.6-flare-vip1K / 2K / 4Klow / medium / high调用方式与 gpt-image-2.6-flare 相同;不传 quality 则自动判断
gpt-image-2.6-sunburst-vip1K / 2K / 4Klow / medium / high调用方式与 gpt-image-2.6-flare-vip 相同

以上均走同一套 /v1/videos 异步流程,仅 model、分辨率控档方式与质量不同;计费与渠道路由以 model 区分。

请求头

参数名类型必填说明
Authorizationstring是Bearer YOUR_API_KEY
Content-Typestring是application/json

请求参数

参数名类型必填说明
modelstring是模型名称,见上表。大小写须与上表一致(2K/4K 为大写 K;gpt-image-2.5、gpt-image-2.6 中间是点号)
promptstring是文本提示词
aspect_ratiostring否宽高比。传固定比例字符串(见下表)则精确控制;传 "auto" 或不传则根据提示词自动推断。与 size 二选一
sizestring否像素尺寸,格式 "宽x高"(如 "1280x720"、"1456x624"、"3696x1584")。按对照表选 1K / 2K / 4K 列即可直接出对应分辨率。与 aspect_ratio 二选一
image_sizestring否分辨率档位:1K、2K、4K(大写 K)。与 resolution 完全等价,只传其中一个。配合 aspect_ratio 使用;gpt-image-2.5 仅允许 1K(可不传,默认 1K)
resolutionstring否与 image_size 通用、等价,取值同样是 1K / 2K / 4K。不要与 image_size 同时传不同值
qualitystring否仅 -vip 模型:low、medium、high。不传则自动判断。其余模型质量已固定为 medium,可不传
imagesstring[]否参考图片数组(支持 Base64 或 URL),最多 8 张。传此参数为图生图模式,不传或传空数组为文生图模式

aspect_ratio 支持的值

值方向适用场景
auto自动不指定比例,根据提示词内容自动推断(与不传等价)
1:1正方形通用、社交媒体
16:9横向(宽屏)横屏内容、PC 端
9:16竖向短视频、手机竖屏
4:3横向传统屏幕
3:4竖向竖屏内容
3:2横向摄影常用
2:3竖向竖版海报
5:4横向大幅横图
4:5竖向Instagram 竖图
21:9超宽横向影院宽幅

比例与 size 对照

分辨率固定的模型:gpt-image-2 用 1K 列,gpt-image-2-2K 用 2K 列,gpt-image-2-4K 用 4K 列,gpt-image-2.5 只用 1K 列。
可用参数选档的模型:三列都可用,见下方「分辨率控制」。

比例1K2K4K
1:11024x10242048x20482880x2880
16:91280x7202560x14403840x2160
9:16720x12801440x25602160x3840
3:21248x8322496x16643504x2336
2:3832x12481664x24962336x3504
4:31152x8642304x17283264x2448
3:4864x11521728x23042448x3264
5:41120x8962240x17923200x2560
4:5896x11201792x22402560x3200
21:91456x6243024x12963696x1584

分辨率控制

image_size 与 resolution 是通用字段,语义完全相同,取值均为 1K / 2K / 4K(大写 K),只传其中一个。下面两种选档方式只用于可用参数选档的模型。gpt-image-2、gpt-image-2-2K、gpt-image-2-4K、gpt-image-2.5 分辨率固定,不靠这两个字段换档。

模型可用档位说明
gpt-image-21K分辨率固定
gpt-image-2-2K2K分辨率固定
gpt-image-2-4K4K分辨率固定
gpt-image-2.5仅 1K分辨率固定;不要传 2K / 4K;size 只取上表 1K 列
gpt-image-2-medium、gpt-image-2-vip1K / 2K / 4K用参数选档,调用方式与 gpt-image-2.5-flare 相同
gpt-image-2.5-flare、gpt-image-2.5-sunburst 及其 -vip1K / 2K / 4K用参数选档;不要改成带 -2K / -4K 后缀的模型名
gpt-image-2.6-flare、gpt-image-2.6-sunburst 及其 -vip1K / 2K / 4K用参数选档,调用方式与 gpt-image-2.5-flare 相同

方式一:size 直接传目标像素(与 aspect_ratio 二选一)

按上表选对应列的 "宽x高",像素本身就决定了 1K / 2K / 4K,不必再传 image_size / resolution。例如 "size": "1456x624" 为 21:9 的 1K,2K 用 "3024x1296",4K 用 "3696x1584"。分辨率固定为 1K 的 gpt-image-2、gpt-image-2.5 只能传 1K 列;gpt-image-2-2K 用 2K 列,gpt-image-2-4K 用 4K 列。可用参数选档的模型三列都可传。

方式二:aspect_ratio + image_size 或 resolution

aspect_ratio 传固定比例(如 "21:9");档位用 image_size 或 resolution(二者等价)。例如 "aspect_ratio": "21:9" + "image_size": "4K" 即为 21:9 的 4K。gpt-image-2.5 档位只能是 1K 或不传。gpt-image-2、gpt-image-2-2K、gpt-image-2-4K 的分辨率看模型名,不要靠 image_size / resolution 换档。

宽高比 / 分辨率控制方式对比

方式用法效果
像素尺寸"size": "1456x624" 或 "size": "3696x1584"直接按像素出 1K / 2K / 4K,与 aspect_ratio 二选一
比例 + 档位"aspect_ratio": "21:9" + "image_size" / "resolution"比例与分辨率分开传;两字段通用等价
固定比例"aspect_ratio": "9:16"精确输出指定比例。分辨率固定的模型看 model;可用参数选档的模型可再加 image_size / resolution
自动推断"aspect_ratio": "auto" 或两者均不传根据提示词内容自动决定,无固定比例
提示词描述不传或传 "auto",prompt 中写明比例模型从提示词中读取比例并遵循

质量 quality

非 -vip 模型质量固定为 medium,可不传 quality。

-vip 模型在顶层传 quality:

值说明
low低质量
medium中等质量
high高质量
不传自动判断

适用模型:gpt-image-2-vip、gpt-image-2.5-flare-vip、gpt-image-2.5-sunburst-vip、gpt-image-2.6-flare-vip、gpt-image-2.6-sunburst-vip。调用方式相同,只换 model。

images 数组元素传法

方式示例
图片 URL"https://example.com/reference.jpg"
Base64"data:image/jpeg;base64,/9j/4AAQSkZJRg..."

注意:传入图片 URL 时,网关会自动将其下载并转为 Base64 后发给上游,请确保 URL 为可公网访问的图片直链。

请求示例

文生图 — 固定比例

json
{
  "model": "gpt-image-2",
  "prompt": "生成抖音带货风格主图,主体 xxx",
  "aspect_ratio": "9:16"
}

gpt-image-2.5 同用法,分辨率固定 1K。要固定 2K / 4K,把 model 改成 gpt-image-2-2K / gpt-image-2-4K。不传或 "auto" 则按提示词自动推断比例。

文生图 — size 像素(flare / sunburst 选 1K / 2K / 4K)

json
{
  "model": "gpt-image-2.5-flare",
  "prompt": "做个广告",
  "size": "1456x624"
}

对照表 1K 列即 1K;2K 用 "3024x1296",4K 用 "3696x1584"。gpt-image-2.5 只能用 1K 列。gpt-image-2.5-sunburst、gpt-image-2-medium、gpt-image-2-vip、gpt-image-2.6-flare / sunburst 以及对应 -vip 把 model 换掉即可。

文生图 — 比例 + 分辨率(flare / sunburst)

json
{
  "model": "gpt-image-2.5-flare",
  "prompt": "做个广告",
  "aspect_ratio": "21:9",
  "image_size": "4K"
}

image_size 与 resolution 等价,只传一个。gpt-image-2.5-sunburst、gpt-image-2-medium、gpt-image-2.6-flare / sunburst 把 model 换掉即可。-vip 在此基础上再加 quality,见下例。

文生图 — vip 指定质量

json
{
  "model": "gpt-image-2-vip",
  "prompt": "做个广告",
  "aspect_ratio": "21:9",
  "image_size": "4K",
  "quality": "high"
}

quality 取值 low / medium / high;不传则自动判断。gpt-image-2.5-flare-vip、gpt-image-2.5-sunburst-vip、gpt-image-2.6-flare-vip、gpt-image-2.6-sunburst-vip 把 model 换掉即可。非 -vip 质量固定 medium,可不传 quality。

图生图

json
{
  "model": "gpt-image-2.5-flare",
  "prompt": "做个广告",
  "aspect_ratio": "21:9",
  "image_size": "4K",
  "images": [
    "https://www.baidu.com/img/PCtm_d9c8750bed0b3c7d089fa7d55720d6cf.png"
  ]
}

images 也可传 Base64(data:image/jpeg;base64,...)。不传或空数组为文生图。

响应参数

图片任务也走 /v1/videos,object 固定为 "video"。完成态图片地址位于顶层 url 和 image_url,两者值相同。

参数名类型说明
idstring任务 ID,格式:task_xxxx
objectstring固定值:video(图片任务也是,类型看 model)
modelstring使用的模型名称
statusstring任务状态:queued(排队中)、in_progress(处理中)、completed(已完成)、failed(失败)
progressnumber任务进度,0–100
created_atnumber创建时间戳(秒)
completed_atnumber完成时间戳(秒),仅在 completed 或 failed 状态返回
urlstring生成的图片 URL,仅 completed 返回
image_urlstring与 url 同值,仅 completed 返回
errorobject错误信息,仅在 failed 状态返回
error.messagestring失败原因描述
error.codestring错误码,如 upstream_error

响应示例

提交成功(排队中)

json
{
  "id": "task_1776831820897",
  "object": "video",
  "model": "gpt-image-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1709876543
}

任务处理中

json
{
  "id": "task_1776831820897",
  "object": "video",
  "model": "gpt-image-2",
  "status": "in_progress",
  "progress": 10,
  "created_at": 1709876543
}

任务完成

json
{
  "id": "task_1776831820897",
  "object": "video",
  "model": "gpt-image-2",
  "status": "completed",
  "progress": 100,
  "created_at": 1709876543,
  "completed_at": 1709876598,
  "url": "https://example.com/uploads/gpt-images/task_1776831820897.png",
  "image_url": "https://example.com/uploads/gpt-images/task_1776831820897.png"
}

任务失败

json
{
  "id": "task_1776831820897",
  "object": "video",
  "model": "gpt-image-2",
  "status": "failed",
  "created_at": 1718123456,
  "completed_at": 1718123456,
  "progress": 100,
  "error": {
    "message": "上游任务失败原因",
    "code": "upstream_error"
  }
}

任务查询接口

接口地址

GET/v1/videos/{task_id}

请求示例

bash
curl -X GET https://xxx.com/v1/videos/task_1776831820897 \
  -H "Authorization: Bearer YOUR_API_KEY"

响应说明

返回字段与提交接口一致,根据 status 字段判断任务是否完成:

  • queued / in_progress:任务未完成,继续轮询
  • completed:任务完成,从顶层 url 或 image_url 获取图片地址
  • failed:任务失败,从 error.message 获取错误原因

注意事项

  1. 接口复用:GPT 图片生成使用 /v1/videos 接口,与视频生成共用,通过 model 参数区分;支持 gpt-image-2、gpt-image-2-2K、gpt-image-2-4K、gpt-image-2-medium、gpt-image-2-vip、gpt-image-2.5、gpt-image-2.5-flare、gpt-image-2.5-sunburst、gpt-image-2.5-flare-vip、gpt-image-2.5-sunburst-vip、gpt-image-2.6-flare、gpt-image-2.6-sunburst、gpt-image-2.6-flare-vip、gpt-image-2.6-sunburst-vip
  2. 参数位置:aspect_ratio、size、image_size、resolution、quality、images 均为顶层字段,直接放在请求体根对象中
  3. 宽高比 / 分辨率:
    • 传 size(如 "1456x624"、"3696x1584")→ 直接按像素出 1K / 2K / 4K,与 aspect_ratio 二选一,取值见上表
    • 传 aspect_ratio + image_size 或 resolution → 比例与档位分开控制;image_size 与 resolution 通用等价(1K/2K/4K),只传一个
    • 传 "auto" 或不传 aspect_ratio/size → 完全等价,根据提示词内容自动推断;提示词中若描述了比例,模型会据此生成
    • 分辨率固定:gpt-image-2(1K)、gpt-image-2-2K(2K)、gpt-image-2-4K(4K)、gpt-image-2.5(仅 1K)
    • 可用参数选 1K / 2K / 4K:gpt-image-2-medium、gpt-image-2-vip、gpt-image-2.5-flare / sunburst 及其 -vip、gpt-image-2.6-flare / sunburst 及其 -vip
  4. 质量:非 -vip 固定 medium,可不传 quality。-vip 传 low / medium / high,不传则自动判断
  5. 参考图片格式:支持 JPEG、PNG、WEBP 格式
  6. 参考图片来源:支持两种格式
    • Base64 格式:需包含完整的 Data URL 前缀(如:data:image/jpeg;base64,)
    • URL 格式:直接传入可访问的图片 URL 地址
  7. 任务模式:
    • 不传 images 或传空数组 = 文生图模式
    • images 包含图片(Base64 或 URL)= 图生图模式
  8. 异步处理:接口返回任务 ID 后,轮询 GET /v1/videos/{task_id},建议间隔 2~5 秒。completed 读取顶层 url 或 image_url(两者同值)