1. 通用规范
统一鉴权
Authorization: Bearer YOUR_API_KEY推荐请求头
Accept: application/json基础约定
- 上游接口以异步任务模式为主:创建任务 → 轮询任务 → 获取结果/下载结果。
- 状态字段建议统一按小写处理。
- 任务状态显示成功时,仍需确认是否存在可下载结果。
- 视频结果优先落地到本地文件,再返回本地可访问地址给前端。
2. 图片生成规范
图片接口覆盖 Nano Banana、GPT Image-2、Grok Imagine Image 等模型。生产环境建议优先使用异步接口。
当前启用模型
| 展示名 | 模型 ID | 上游类型 | 参考图 | 上限 |
|---|---|---|---|---|
| Nano Banana 2 | gemini-3.1-flash-image-preview | nano-banana-async | 支持 | 4 |
| Nano Banana Pro | gemini-3-pro-image-preview | nano-banana-async | 支持 | 4 |
| GPT Image-2 | gpt-image-2 | gpt-image-2-async | 支持 | 14 |
| Grok Imagine Image | grok-imagine-image | grok-image-async | 支持 | 1 |
| Grok Imagine Image Lite | grok-imagine-image-lite | grok-image-async | 不支持 | 0 |
| Grok Imagine Image Pro | grok-imagine-image-pro | grok-image-async | 支持 | 1 |
本地统一入口
POST /api/images/generate
Content-Type: application/json
本地请求体
{
"model": "gemini-3.1-flash-image-preview",
"prompt": "A premium studio product shot",
"aspectRatio": "16:9",
"candidateCount": 1,
"variantIndex": 0,
"referenceImages": [],
"params": {
"imageSize": "1K"
},
"requestId": "optional-id"
}
图片上游统一端点
异步创建
POST /v1/images/generations/async异步查询
GET /v1/images/tasks/{task_id}结果内容
GET /v1/images/tasks/{task_id}/content?index=02.6 Nano Banana 接口规范
适用模型
gemini-3.1-flash-image-previewgemini-3-pro-image-preview
规格
- 请求格式:
application/json - 尺寸档位:
1K / 2K / 4K - 参考图最多:4 张
字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
model | string | 模型 ID |
prompt | string | 提示词 |
size | string | 比例字符串,如 16:9 |
quality | string | 1K / 2K / 4K |
n | number | 候选数量 |
image | string | string[] | 参考图,建议传 data:image/...;base64,... |
文生图示例
{
"model": "gemini-3.1-flash-image-preview",
"prompt": "A premium studio product shot of a banana on a clean background",
"size": "16:9",
"quality": "2K",
"n": 1
}
支持比例
1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 1:4 1:8 4:1 8:1
2.7 GPT Image-2 接口规范
适用于文生图、图生图、多图融合、局部重绘。正式生产环境推荐使用异步创建。
接口概览
POST /v1/images/generations同步创建POST /v1/images/generations/async异步创建GET /v1/images/tasks/{task_id}查询GET /v1/images/tasks/{task_id}/content?index=0获取结果
请求格式
- 纯文生图:
application/json - 图生图 / 多图融合 / 局部重绘:
multipart/form-data - 统一处理时也可全部使用
multipart/form-data
字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 固定 gpt-image-2 |
prompt | string | 是 | 生成提示词 |
size | string | 否 | 输出尺寸,如 1024x1024、2048x2048、3840x2160 |
quality | string | 否 | low / medium / high / auto,默认建议 auto |
n | number | 否 | 生成数量 |
response_format | string | 否 | url / b64_json,默认建议 url |
image | file | 否 | 单图参考 |
image[] | file[] | 否 | 多图参考 |
mask | file | 否 | 局部重绘蒙版 |
推荐尺寸
| 尺寸 | 比例 | 说明 |
|---|---|---|
1024x1024 | 1:1 | 方图,通用默认尺寸 |
1536x1024 | 3:2 | 横图 |
1024x1536 | 2:3 | 竖图 |
2048x2048 | 1:1 | 高分辨率方图 |
2048x1152 | 16:9 | 2K 横版 |
3840x2160 | 16:9 | 4K 横版 |
2160x3840 | 9:16 | 4K 竖版 |
3696x1584 | 21:9 | 超宽屏 |
3840x1280 | 3:1 | 超宽屏 |
auto | 自动 | 由平台/模型自动决定输出尺寸 |
尺寸约束
- 最大边长不得超过
3840 - 宽高必须为
16的倍数 - 长宽比不超过
3:1 - 总像素范围
655,360 ~ 8,294,400
质量参数
auto:默认推荐high:正式交付、海报、商品图medium:常规生成low:快速预览或成本敏感
文生图示例
{
"model": "gpt-image-2",
"prompt": "Create a clean modern product poster with a white background",
"size": "1024x1024",
"quality": "auto",
"n": 1,
"response_format": "url"
}
高质量 4K 横版示例
{
"model": "gpt-image-2",
"prompt": "Create a premium studio product poster with cinematic lighting",
"size": "3840x2160",
"quality": "high",
"n": 1,
"response_format": "url"
}
图生图示例
curl -X POST 'https://www.zexitongxue.com/v1/images/generations/async' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-F 'model=gpt-image-2' \
-F 'prompt=Enhance the image while preserving the subject' \
-F 'size=1024x1024' \
-F 'quality=auto' \
-F 'response_format=url' \
-F 'image=@input.png'
结果读取
任务成功后,结果通常出现在
result_url、data.data[0].url 或 data.data[0].b64_json。- 当结果是
https://...时,客户端可直接下载。 - 当结果是
data:image/...;base64,...时,客户端应截取逗号后的 Base64 内容并解码保存。 - 当结果是
b64_json时,客户端直接 Base64 解码保存。
下载最终图片
curl -L 'https://www.zexitongxue.com/v1/images/tasks/{task_id}/content?index=0' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-o result.png
2.8 Grok 生图接口规范
适用模型
grok-imagine-imagegrok-imagine-image-litegrok-imagine-image-pro
参考图限制
grok-imagine-image:最多 1 张grok-imagine-image-pro:最多 1 张grok-imagine-image-lite:不支持参考图
示例
{
"model": "grok-imagine-image",
"prompt": "A cinematic portrait with dramatic lighting",
"size": "9:16",
"n": 1
}
支持比例
1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9
3. 视频生成规范
视频接口统一使用 /v1/videos 创建、查询和下载任务。
已联调成功模型清单
| 模型 ID | 说明 | 已验证时长 | 建议比例 |
|---|---|---|---|
grok-imagine-1.0-video | 通用视频生成 | 6 / 10 / 12 / 16 / 20 | 16:9 |
grok-imagine-1.0-video-landscape-15s | 横屏 15s 固定时长 | 15 | 16:9 |
grok-imagine-1.0-video-portrait-10s | 竖屏 10s 固定时长 | 10 | 9:16 |
grok-imagine-1.0-video-portrait-15s | 竖屏 15s 固定时长 | 15 | 9:16 |
sora-v3-fast | Seedance 2.0 Fast 视频生成 | 5-15 秒整数 | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 |
sora-v3-pro | Seedance 2.0 视频生成 | 5-15 秒整数 | 16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9 |
sora2 | Sora2 视频生成 | 4 / 8 / 12 | 16x9 / 9x16 |
sora2-pro | Sora2 Pro 视频生成 | 4 / 8 / 12 | 16x9 / 9x16 / 1792x1024 / 1024x1792 |
Seedance 使用接口模型 ID
sora-v3-fast / sora-v3-pro,请求参数按 Seedance 示例中的 video_config、reference_images、metadata 等字段提交。统一端点
创建任务
POST /v1/videos查询任务
GET /v1/videos/{task_id}获取内容
GET /v1/videos/{task_id}/contentSeedance 文生视频
{
"model": "sora-v3-fast",
"prompt": "A cinematic tracking shot through a neon-lit rainy street at night",
"video_config": {
"aspect_ratio": "16:9",
"resolution_name": "720p",
"video_length": 5
}
}
Seedance 图生视频
{
"model": "sora-v3-pro",
"prompt": "Turn this still image into a polished fashion film with subtle camera motion",
"reference_images": [
"https://example.com/look-1.jpg"
],
"video_config": {
"aspect_ratio": "16:9",
"resolution_name": "720p",
"video_length": 8,
"reference_mode": "auto"
}
}
Seedance 请求参数以文档中的
video_config、reference_images、metadata 等字段为准。Sora2 示例
curl -X POST 'https://www.zexitongxue.com/v1/videos' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"model": "sora2",
"prompt": "A slow aerial shot over a quiet neon city at night",
"size": "16x9",
"duration": 4
}'
状态与轮询
建议创建任务后每 10s ~ 20s 轮询一次 GET /v1/videos/{task_id},直到进入成功态或失败态。
进行中状态
submitted pending queued processing running in_progress
失败状态
failed failure error cancelled canceled
下载视频
curl -L 'https://www.zexitongxue.com/v1/videos/task_xxx/content' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-o result.mp4
视频链路不能只看任务状态成功,还必须确认存在可下载结果,并成功下载落地。
4. 推荐使用流程
图片流程
- 选择模型
- 组装请求参数
- 调用
/api/images/generate或上游异步接口 - 等待结果或轮询任务
- 返回图片 URL / data URL / Base64 结果
视频流程
- 选择成功模型
- 按模型类型组装参数,Seedance 使用
video_config结构 - 调用
POST /v1/videos - 轮询
GET /v1/videos/{task_id} - 获取结果地址或调用
/content - 下载落地到本地
5. 实施检查点
- 模型 ID 是否在允许列表内。
- 比例 / 尺寸是否满足模型约束。
- 时长是否匹配视频模型限制。
- 参考图数量和字段结构是否匹配模型要求。
- 视频下载是否带
Authorization。 - 视频成功后是否真的拿到可下载 URL。
- 视频是否已成功落地并返回本地地址。