泽西童学 · 技术接入手册

图片及视频接口规范
整理版 V4

面向客户技术接入的接口手册,覆盖鉴权、图片生成、视频生成、异步任务、结果读取、尺寸与质量控制等关键内容。

版本号:V4.0 更新日期:2026-05-18 主基地址:https://www.zexitongxue.com

1. 通用规范

统一鉴权

Authorization: Bearer YOUR_API_KEY

推荐请求头

Accept: application/json

基础约定

  • 上游接口以异步任务模式为主:创建任务 → 轮询任务 → 获取结果/下载结果。
  • 状态字段建议统一按小写处理。
  • 任务状态显示成功时,仍需确认是否存在可下载结果。
  • 视频结果优先落地到本地文件,再返回本地可访问地址给前端。

2. 图片生成规范

图片接口覆盖 Nano Banana、GPT Image-2、Grok Imagine Image 等模型。生产环境建议优先使用异步接口。

当前启用模型

展示名模型 ID上游类型参考图上限
Nano Banana 2gemini-3.1-flash-image-previewnano-banana-async支持4
Nano Banana Progemini-3-pro-image-previewnano-banana-async支持4
GPT Image-2gpt-image-2gpt-image-2-async支持14
Grok Imagine Imagegrok-imagine-imagegrok-image-async支持1
Grok Imagine Image Litegrok-imagine-image-litegrok-image-async不支持0
Grok Imagine Image Progrok-imagine-image-progrok-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=0

2.6 Nano Banana 接口规范

适用模型

  • gemini-3.1-flash-image-preview
  • gemini-3-pro-image-preview

规格

  • 请求格式:application/json
  • 尺寸档位:1K / 2K / 4K
  • 参考图最多:4 张

字段说明

字段类型说明
modelstring模型 ID
promptstring提示词
sizestring比例字符串,如 16:9
qualitystring1K / 2K / 4K
nnumber候选数量
imagestring | 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

字段说明

字段类型必填说明
modelstring是固定 gpt-image-2
promptstring是生成提示词
sizestring否输出尺寸,如 1024x1024、2048x2048、3840x2160
qualitystring否low / medium / high / auto,默认建议 auto
nnumber否生成数量
response_formatstring否url / b64_json,默认建议 url
imagefile否单图参考
image[]file[]否多图参考
maskfile否局部重绘蒙版

推荐尺寸

尺寸比例说明
1024x10241:1方图,通用默认尺寸
1536x10243:2横图
1024x15362:3竖图
2048x20481:1高分辨率方图
2048x115216:92K 横版
3840x216016:94K 横版
2160x38409:164K 竖版
3696x158421:9超宽屏
3840x12803: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-image
  • grok-imagine-image-lite
  • grok-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 / 2016:9
grok-imagine-1.0-video-landscape-15s横屏 15s 固定时长1516:9
grok-imagine-1.0-video-portrait-10s竖屏 10s 固定时长109:16
grok-imagine-1.0-video-portrait-15s竖屏 15s 固定时长159:16
sora-v3-fastSeedance 2.0 Fast 视频生成5-15 秒整数16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9
sora-v3-proSeedance 2.0 视频生成5-15 秒整数16:9 / 9:16 / 1:1 / 4:3 / 3:4 / 21:9
sora2Sora2 视频生成4 / 8 / 1216x9 / 9x16
sora2-proSora2 Pro 视频生成4 / 8 / 1216x9 / 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}/content

Seedance 文生视频

{
  "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. 推荐使用流程

图片流程

  1. 选择模型
  2. 组装请求参数
  3. 调用 /api/images/generate 或上游异步接口
  4. 等待结果或轮询任务
  5. 返回图片 URL / data URL / Base64 结果

视频流程

  1. 选择成功模型
  2. 按模型类型组装参数,Seedance 使用 video_config 结构
  3. 调用 POST /v1/videos
  4. 轮询 GET /v1/videos/{task_id}
  5. 获取结果地址或调用 /content
  6. 下载落地到本地

5. 实施检查点

  • 模型 ID 是否在允许列表内。
  • 比例 / 尺寸是否满足模型约束。
  • 时长是否匹配视频模型限制。
  • 参考图数量和字段结构是否匹配模型要求。
  • 视频下载是否带 Authorization。
  • 视频成功后是否真的拿到可下载 URL。
  • 视频是否已成功落地并返回本地地址。