图片生成

创建图片，处理直接返回图片或异步任务两种响应，了解输入参数和计价限制。

同步与异步响应形状

图片生成使用专用接口，不使用聊天 messages。响应有两种已支持的形状，不能无条件读取任务 id：同步响应直接在 data[] 中返回带 url 的图片，此时没有任务可轮询；异步响应返回任务 id 和 status（通常为 PENDING），应用才需要查询到 SUCCEEDED 后读取图片 URL。两种形状都没有可用图片 URL，且也没有异步任务的 id 与 status 时，应报错而不是猜测结果。

本文用 GFW 模型 ID qwen-image-plus 演示请求格式。使用前在模型库确认它仍可用、通道接受所需尺寸。示例响应不是实际生成结果。

端点与鉴权

操作	端点
创建任务	`POST https://api.gfw.net/v1/images/generations`
查询任务	`GET https://api.gfw.net/v1/images/generations/{id}`
鉴权	以上请求均使用 `Authorization: Bearer $GFW_API_KEY`
获取图片	完成后读取 `data[].url`，向返回 URL 发起 GET

虽然创建路径与 OpenAI 图片接口相似，GFW 可能返回立即可用的 data[].url，也可能返回异步任务。cURL/Python 示例都会先检查 data[] 中是否有图片 URL；有 URL 就直接输出，不发起轮询；否则才读取 id/status 并轮询。不要假设 SDK 的 images.generate() 永远只返回其中一种形状，初次接入建议按本页使用 HTTP 请求处理响应。

请求参数

字段	类型	必填	说明
`model`	string	是	GFW 图片模型 ID
`prompt`	string	是	非空生成提示
`n`	integer	否	请求数量，省略或非正值在入口按 1 处理；可生成数量仍受模型限制
`size`	string	否	模型接受的尺寸字符串，例如 `1024x1024`；可选尺寸不是跨模型统一集合
`images`	array of strings	否	参考图输入，仅在支持相应图生图能力的模型与通道上使用
其他字段	依模型而定	否	通用请求体可转发，但不保证 `quality`、`response_format` 等参数在每种通道有效

当前通用入口按 size 最大边长匹配图片价格档位。尺寸可能同时影响模型可用性与费用，不能只为降低费用随意填一个不被模型支持的值。图生图字符串应使用什么 URL 或编码形式，需确认该模型通道的规则；不要套用对话视觉输入的通用限制。

完整创建与轮询示例

设置 GFW_API_KEY。cURL 示例依赖本地 Python 解析返回的 JSON；Python 示例依赖 requests 包。两种示例都会先处理同步 data[].url，只有异步响应才提交一次轮询，轮询等待上限为 300 秒。

set -eu
: "${GFW_API_KEY:?请先设置 GFW_API_KEY}"

created=$(curl --fail-with-body --silent --show-error --max-time 60 \
  https://api.gfw.net/v1/images/generations \
  -H "Authorization: Bearer ${GFW_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{"model":"qwen-image-plus","prompt":"白色马克杯放在木桌上，柔和自然光，简洁构图。","n":1,"size":"1024x1024"}')

direct_urls=$(printf '%s' "$created" | python -c 'import json,sys; d=json.load(sys.stdin); data=d.get("data",[]) if isinstance(d,dict) else []; print("\n".join(item["url"] for item in data if isinstance(item,dict) and item.get("url")))')
if [ -n "$direct_urls" ]; then
  printf '%s\n' "$direct_urls"
  exit 0
fi

task_id=$(printf '%s' "$created" | python -c 'import json,sys; d=json.load(sys.stdin); print(d.get("id","") if isinstance(d,dict) else "")')
task_status=$(printf '%s' "$created" | python -c 'import json,sys; d=json.load(sys.stdin); print(d.get("status","") if isinstance(d,dict) else "")')
if [ -z "$task_id" ] || [ -z "$task_status" ]; then
  printf '响应既没有 data[].url，也没有异步任务 id/status\n' >&2
  exit 1
fi
printf '任务 ID：%s（状态：%s）\n' "$task_id" "$task_status"
started=$SECONDS
while (( SECONDS - started < 300 )); do
  result=$(curl --fail-with-body --silent --show-error --max-time 30 \
    "https://api.gfw.net/v1/images/generations/${task_id}" \
    -H "Authorization: Bearer ${GFW_API_KEY}")
  status=$(printf '%s' "$result" | python -c 'import json,sys; print(json.load(sys.stdin).get("status",""))')
  case "$status" in
    SUCCEEDED)
      printf '%s' "$result" | python -c 'import json,sys; d=json.load(sys.stdin); urls=[x["url"] for x in d.get("data",[]) if x.get("url")]; assert urls,"完成但未返回图片 URL"; print("\n".join(urls))'
      exit 0 ;;
    FAILED)
      printf '图片任务失败：%s\n' "$result" >&2
      exit 1 ;;
  esac
  sleep 3
done
printf '轮询超时，请保存任务 ID，稍后查询；不要重复提交。\n' >&2
exit 1

Shell 示例使用 Bash 的 SECONDS 与算术条件，请用 Bash 执行。300 秒是示例轮询预算，不是生成完成承诺；可根据应用总时限调整。HTTP 单次超时与整体截止时间是不同限制，失败或超时后不要自动重新创建任务。

任务响应字段

同步响应结构示意（直接返回图片，不含任务 id）：

{
  "object": "image.generation",
  "data": [{"url": "https://api.gfw.net/media/images/example.png"}]
}

异步创建响应结构示意：

{"id":"img_example","object":"image.generation","status":"PENDING"}

异步完成后的查询响应结构示意，URL 只是格式示例，不是实际文件：

{
  "id": "img_example",
  "object": "image.generation",
  "model": "qwen-image-plus",
  "status": "SUCCEEDED",
  "data": [{"url": "https://api.gfw.net/media/images/example.png"}],
  "image_urls": ["https://example.invalid/upstream-image.png"]
}

字段	处理建议
`id`	仅异步响应提供；保存并用它查询现有任务，不要根据 ID 格式猜测后端通道
`status`	仅异步响应提供；`PENDING` / 运行中状态表示继续等待；`SUCCEEDED` 与 `FAILED` 为终态
`data[].url`	优先用于获取图片；可能是平台缓存 URL，也可能是上游 URL
`image_urls`	补充结果字段，可能包含原始 URL 或路径，不优先于 `data[].url`
`data[].b64_json`	某些兼容上游可能提供的 Base64 图片字段；只有模型契约明确返回时才解码，不能把它臆造为本入口的响应

通用后台处理器可将上游 Base64 结果保存为文件后返回 URL，因此不能要求响应一定有 b64_json。本入口已核对的可用图片形状是 data[].url；若实际响应只有未在模型契约中声明的 Base64 字段，应按不支持处理。异步任务失败未必提供详细错误文字，应用应至少保存任务 ID 与最后状态。

文件、计费与相关文档

完成后及时将图片下载到你的受控存储，不能把任务 URL 当作永久资产地址。下载媒体 URL 时不要向未知上游域名附带 GFW API Key；对链接和下载大小进行必要限制。

图片按张数及模型尺寸档位等规则计价，不按聊天输出 Token 定价。创建成功只表示任务已受理，不表示图片已成功或账单已结算。费用以计费与充值和用量与调用日志为准。

相关文档：视频生成、模型与能力、错误码与重试。

同步与异步响应形状复制章节链接

端点与鉴权复制章节链接

请求参数复制章节链接

完整创建与轮询示例复制章节链接

任务响应字段复制章节链接