ZCloudAPI 对 GPT Image、Gemini 生图和 Grok 生图提供统一接口。客户端不需要判断上游厂商，也不需要处理 Chat Completions、Responses 或 Gemini 原生响应。

功能	统一接口	请求格式	非流式响应	流式响应
生成图片	POST /v1/images/generations	application/json	data[].url 或 data[].b64_json	图片 SSE
编辑图片	POST /v1/images/edits	multipart/form-data	data[].url 或 data[].b64_json	图片 SSE

第一步：准备 API Key

macOS / Linux：

export ZCLOUD_API_KEY="sk-你的-ZCloudAPI-Key"
export ZCLOUD_BASE_URL="https://api.zcloudapi.com/v1"

Windows PowerShell：

$env:ZCLOUD_API_KEY="sk-你的-ZCloudAPI-Key"
$env:ZCLOUD_BASE_URL="https://api.zcloudapi.com/v1"

查询当前 Key 能使用的模型：

curl "$ZCLOUD_BASE_URL/models" \
  -H "Authorization: Bearer $ZCLOUD_API_KEY"

模型是否可用由 Key 所属分组决定。实际价格以 模型广场 为准。

第二步：选择模型

厂商	当前对外模型	生成	编辑	主要参数
GPT	gpt-image-1k、gpt-image-2k、gpt-image-4k	支持	支持	模型名决定固定尺寸和质量
Gemini	gemini-3.1-flash-image、gemini-3-pro-image	支持	支持	aspect_ratio、resolution、image_size
Grok	grok-imagine-image 系列	支持	取决于上游权限	aspect_ratio、resolution、quality、n

GPT 固定规格别名在平台内部映射到实际上游模型。客户端只调用上表中的对外模型，不需要知道或直接调用内部模型名。

GPT 固定规格如下：

模型	固定输出尺寸	固定质量	当前售价
gpt-image-1k	1024x1024	high	$0.20/张
gpt-image-2k	2048x2048	high	$0.20/张
gpt-image-4k	3840x2160	high	$0.40/张

这三个别名会在服务端覆盖调用方传入的 size 和 quality。选择模型就是选择最终规格。

第三步：按厂商调用

调用规则只有三条：

• 生成图片都调用 POST /v1/images/generations，并发送 JSON。
• 编辑图片都调用 POST /v1/images/edits，并以 multipart/form-data 上传图片。
• model 决定实际厂商；平台在内部转换厂商协议。非流式请求统一返回 data[].url 或 data[].b64_json，流式请求返回 SSE 事件。

GPT Image 生成

GPT 对外模型是固定规格商品。例如生成 4K、16:9、High 图片：

curl "$ZCLOUD_BASE_URL/images/generations" \
  -H "Authorization: Bearer $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-4k",
    "prompt": "一张未来城市夜景，电影感灯光，画面中不要出现文字",
    "n": 1,
    "response_format": "url"
  }'

调用 gpt-image-1k、gpt-image-2k 或 gpt-image-4k 时，服务端会按模型名强制规格。客户端另传 size、quality、aspect_ratio 或 resolution 不会改变最终规格。

GPT Image 编辑

curl "$ZCLOUD_BASE_URL/images/edits" \
  -H "Authorization: Bearer $ZCLOUD_API_KEY" \
  -F "model=gpt-image-1k" \
  -F "image=@input.png" \
  -F "prompt=保留主体，把背景改成浅灰色，不要添加文字" \
  -F "response_format=url"

Gemini 生成

Gemini 可以显式选择宽高比和分辨率：

curl "$ZCLOUD_BASE_URL/images/generations" \
  -H "Authorization: Bearer $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "一张未来城市夜景，电影感灯光，画面中不要出现文字",
    "n": 1,
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "response_format": "url"
  }'

Gemini 编辑

curl "$ZCLOUD_BASE_URL/images/edits" \
  -H "Authorization: Bearer $ZCLOUD_API_KEY" \
  -F "model=gemini-3.1-flash-image" \
  -F "image=@input.png" \
  -F "prompt=保留主体，把背景改成浅灰色，不要添加文字" \
  -F "aspect_ratio=1:1" \
  -F "resolution=1K" \
  -F "response_format=url"

Gemini 编辑最多支持 14 张参考图，多图时重复传入 image 字段，例如 -F "image=@front.png" -F "image=@background.png"。

Grok 生成

curl "$ZCLOUD_BASE_URL/images/generations" \
  -H "Authorization: Bearer $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image",
    "prompt": "一辆红色跑车停在雨夜街道上",
    "n": 1,
    "aspect_ratio": "16:9",
    "resolution": "2k",
    "quality": "medium",
    "response_format": "url"
  }'

Grok 编辑

curl "$ZCLOUD_BASE_URL/images/edits" \
  -H "Authorization: Bearer $ZCLOUD_API_KEY" \
  -F "model=grok-imagine-image" \
  -F "image=@input.png" \
  -F "prompt=保留构图，把跑车改成银色" \
  -F "aspect_ratio=16:9" \
  -F "resolution=2k" \
  -F "quality=medium" \
  -F "response_format=url"

Grok 编辑协议最多支持 5 张参考图。实际能否生成或编辑仍取决于当前上游渠道的模型权限和可用状态；调用前先以 /v1/models 和模型广场为准。

统一响应

response_format=url 的典型响应：

{
  "created": 1788360000,
  "data": [
    {
      "url": "https://zcloudapi-downloads-sg-2026.oss-ap-southeast-1.aliyuncs.com/..."
    }
  ]
}

图片地址位于 data[0].url。它是有有效期的 OSS 签名 URL，收到后应立即下载到本地或保存到自己的对象存储。

curl -L "把 data[0].url 粘贴到这里" -o generated.png

通用参数

参数	类型	说明
model	string	必填；必须是当前 Key 可见的图片模型
prompt	string	必填；生成或编辑要求
n	integer	图片数量；Gemini 当前只支持 1，GPT/Grok 按上游能力处理
size	string	OpenAI 风格像素尺寸，也可供平台转换为 Gemini 比例和分辨率
aspect_ratio	string	宽高比，例如 1:1、16:9、9:16
resolution	string	分辨率档位，例如 1K、2K、4K
image_size	string	resolution 的 Gemini 兼容别名
quality	string	质量档位；实际可选值取决于模型
response_format	string	url 或 b64_json；省略时默认按 URL 处理
stream	boolean	是否返回图片 SSE；非流式客户端保持 false 或省略

对 Gemini 和 Grok，不要同时传入互相冲突的参数。例如 size=1024x1024 与 aspect_ratio=16:9 表示不同宽高比，平台会直接返回 HTTP 400，不会带着错误参数反复切换渠道。

Gemini 参数规则

Gemini 会把统一参数转换为上游 image_config：

调用方参数	Gemini 上游参数
aspect_ratio=16:9	image_config.aspect_ratio=16:9
resolution=2K	image_config.image_size=2K
image_size=4K	image_config.image_size=4K
size=2752x1536	自动映射为约 16:9 和 2K
只传 quality=high	兼容映射为 2K
不传尺寸与质量	默认 1:1、1K

Gemini 常用比例包括 1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9 和 21:9。部分超宽比例只适用于 Flash 模型，平台会在请求发往上游前校验。

Grok 参数规则

Grok 仍使用统一的生成和编辑接口。平台会把 OpenAI 风格的 size 转成 xAI 实际使用的 aspect_ratio 与 resolution，并移除上游不支持的 stream 字段。

参数	Grok 可选值
n	1 到 10
aspect_ratio	auto、1:1、16:9、9:16、4:3、3:4、3:2、2:3、2:1、1:2、21:9、5:2 等
resolution	1k、2k
quality	low、medium、auto；不支持 high
response_format	url、b64_json

Grok 原生编辑接口要求 JSON，而常见 OpenAI 客户端会发送 multipart。ZCloudAPI 会自动完成 multipart -> JSON 转换，并支持最多 5 张参考图。不同上游账号仍可能拥有不同的模型和编辑权限；若上游返回“不支持参数”或“模型无权限”，平台会返回明确错误，不会把失败伪装成成功图片。

URL 与 Base64

response_format=url：

• ZCloudAPI 获取上游图片后转存到阿里云 OSS。
• 客户端收到 data[0].url。
• 下载流量由 OSS 承担，适合网页展示和普通业务。

response_format=b64_json：

• 客户端收到 data[0].b64_json。
• 不依赖图片域名，适合内网或立即写入本地文件。
• Base64 通常比原始图片大约多三分之一，不要写入普通日志。

Python 解码示例：

import base64
import json

with open("image-response.json", "r", encoding="utf-8") as source:
    response = json.load(source)

with open("generated.png", "wb") as output:
    output.write(base64.b64decode(response["data"][0]["b64_json"]))

流式响应

在生成或编辑请求中传入 stream=true 即可使用 SSE。例如：

curl -N "$ZCLOUD_BASE_URL/images/generations" \
  -H "Authorization: Bearer $ZCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "prompt": "一座雪山下的未来城市，16:9",
    "aspect_ratio": "16:9",
    "resolution": "2K",
    "response_format": "url",
    "stream": true
  }'

GPT 会保留上游提供的预览事件，因此在完成前还可能收到 image_generation.partial_image 事件，预览图片仍可能是 Base64。最终完成事件会按 response_format 转换：url（默认）返回 OSS 图片链接，b64_json 返回 Base64，不需要客户端自行转换上游格式。Gemini 和 Grok 的原生图片接口不返回 SSE，平台会等待图片完成后，再包装成最终完成事件。生成接口的最终事件示例：

event: image_generation.completed
data: {"type":"image_generation.completed","url":"https://..."}

data: [DONE]

编辑接口的完成事件为 image_edit.completed。SSE 返回的是事件，不是非流式 JSON 中的 data[] 外层结构；选择 b64_json 时，完成事件使用 b64_json 字段替代上例的 url。如果不需要预览或事件通知，可以使用更简单的 stream=false。图片生成通常需要几十秒，客户端读取超时建议至少设置为 180 秒。

GPT 原生图片流可能在完成事件后直接结束，不额外发送 [DONE]。客户端应识别 image_generation.completed / image_edit.completed，不要只等待 [DONE]。

Python 完整示例

python -m pip install --upgrade openai requests

import os

import requests
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZCLOUD_API_KEY"],
    base_url="https://api.zcloudapi.com/v1",
    timeout=300.0,
)

result = client.images.generate(
    model="gpt-image-1k",
    prompt="一张极简的云端 API 图标，白色背景，不要文字",
    n=1,
    response_format="url",
)

image = requests.get(result.data[0].url, timeout=120)
image.raise_for_status()
with open("generated.png", "wb") as output:
    output.write(image.content)

扣费规则

图片接口继续使用模型广场配置，不根据上游响应临时改价：

单次 Quota = 模型广场内部单次价格 × Key 所属分组倍率 × 500,000 × n

• n=1 按一张扣费，n=2 按两张扣费。
• 失败且没有生成有效图片的请求不应扣费。
• size、quality、resolution 本身不会绕过模型广场价格；固定规格应选择对应模型名。
• 在控制台「使用日志」中可以核对模型、分组倍率、生成数量和实际 Quota。

兼容说明

历史调用方仍可能通过 Chat Completions、Responses 或 Gemini 原生接口生图，这些路由暂时保留用于兼容旧客户端。新接入统一使用 /v1/images/generations 和 /v1/images/edits，不要再根据厂商分别编写解析逻辑。

常见错误

现象	处理方法
模型不在列表	查询 /v1/models，确认 Key 所属分组包含该模型
参数冲突	只保留一组一致的 size / aspect_ratio / resolution
Gemini 提示 n=1	将 n 改为 1；需要多张时发起多次独立请求
编辑提示缺少 image	使用 multipart/form-data，字段名写成 image
Grok 编辑返回无权限	当前上游未开放编辑模型；更换可用模型或联系管理员
返回 URL 打不开	签名 URL 可能已过期；重新生成并立即下载
Base64 内容很长	直接解码成二进制文件，不要在终端、数据库或普通日志中长期保存
请求超时	将客户端读取超时提高到至少 180 秒，先用 1K、n=1 并降低并发排查