图像生成

接入 GPT Image、Seedream 与其他已配置图像模型。

POST/v1/images/generations
https://api.hanrouter.ai/v1管理 API Key

地址与认证

OpenAI 兼容客户端的 Base URL 为 https://api.hanrouter.ai/v1,请求头为 Authorization: Bearer $HANROUTER_API_KEY。不要重复拼接 /v1。所有厂商都使用本站密钥,不需要向客户端填写上游厂商密钥。

Anthropic SDK 与 Claude Code 的 Base URL 使用 https://api.hanrouter.ai(不含 /v1),由客户端拼接 /v1/messages。Google 模型优先使用本站 OpenAI 兼容接口。

调用前:模型与权限

先调用 GET /v1/models,使用当前 Key 返回的准确图像模型 ID。模型广场用于查看输出类型与价格;列出模型并不保证其每一种接口或参数都可用。Key 所属分组还必须开启图片生成权限。

文生图:最小请求

设置 HANROUTER_API_KEY 后,把 YOUR_IMAGE_MODEL_ID 替换为该 Key 可用的模型 ID。先用 model、prompt、n 发起最小请求;确认模型支持后再添加 size、quality、response_format。下方命令会真正创建生成请求并可能计费。

请求示例
curl --max-time 300 "https://api.hanrouter.ai/v1/images/generations" \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_IMAGE_MODEL_ID",
  "prompt": "A golden bull in front of a modern city skyline, cinematic lighting",
  "n": 1
}'

参数与模型差异

model 为必填字符串;prompt 为必填提示词。n 为图片数量,建议先用 1,最大值由模型决定。size 通常使用“宽x高”,例如 1024x1024,但不是所有模型都接受同一尺寸。quality 与 response_format 的支持及取值也由模型决定,不要将任意厂商的参数直接套用到其他模型。

部分 Gemini 图像模型或渠道使用多模态 Chat Completions / 原生协议,而非 Images 接口。本文的 Images 示例仅适用于支持该路由的渠道;遇到 response_modalities 大小写、协议不兼容等上游错误时,请保留请求 ID 联系支持,不要只更换模型名称反复请求。

图生图与图片编辑

图生图协议按模型区分。支持该用法的 Grok Imagine 渠道可在 POST /v1/images/generations 中添加 image: {"url":"https://..."};这是对象,不是裸 URL 字符串。参考图应可由上游访问。此字段并非所有图片模型通用,使用前请确认所选渠道支持。

请求示例
curl --max-time 300 "https://api.hanrouter.ai/v1/images/generations" \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "YOUR_GROK_IMAGE_MODEL_ID",
  "prompt": "Turn this reference into a watercolor illustration",
  "image": {
    "url": "https://example.com/reference.png"
  }
}'

上传本地图片:multipart 编辑

本站创作页对支持编辑的模型使用 POST /v1/images/edits 上传文件。用 -F 发送 multipart/form-data,由 cURL 自动生成 Content-Type 和 boundary,不要手动设成 application/json。将 reference.png 换成自己的 PNG/JPEG/WebP 文件;格式、大小、mask 及多图能力以模型为准。

请求示例
curl --max-time 300 "https://api.hanrouter.ai/v1/images/edits" \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -F "model=$HANROUTER_IMAGE_MODEL" \
  -F 'prompt=Keep the subject and change the background to a city at sunset' \
  -F 'n=1' \
  -F 'image=@reference.png'

响应:URL 与 Base64

同步成功响应通常在 data[] 中返回 url 或 b64_json。两者是替代格式,不保证同时存在;b64_json 是图片字节的 Base64,需要解码后保存。返回的 URL 可能过期,请及时下载。以下均为结构示例,不是真实生成结果;usage、revised_prompt 等额外字段按实际响应处理。

请求示例
{
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}

{
  "data": [
    {
      "b64_json": "<BASE64_IMAGE_BYTES>"
    }
  ]
}

Python:生成并保存图片

此示例仅使用 Python 标准库。设置 HANROUTER_API_KEY 和 HANROUTER_IMAGE_MODEL 后运行;自动处理 URL 或 Base64 返回,并根据文件头保存 PNG、JPEG 或 WebP。不要把密钥写入源码。

请求示例
import base64, json, os, pathlib, urllib.request

payload = {"model": os.environ["HANROUTER_IMAGE_MODEL"],
           "prompt": "A golden bull in a modern city, cinematic lighting", "n": 1}
request = urllib.request.Request(
    "https://api.hanrouter.ai/v1/images/generations",
    data=json.dumps(payload).encode(),
    headers={"Authorization": "Bearer " + os.environ["HANROUTER_API_KEY"],
             "Content-Type": "application/json"})
with urllib.request.urlopen(request, timeout=300) as response:
    result = json.load(response)
for index, item in enumerate(result["data"], 1):
    if item.get("b64_json"):
        image = base64.b64decode(item["b64_json"])
    else:
        with urllib.request.urlopen(item["url"], timeout=60) as response:
            image = response.read()
    extension = ".png" if image.startswith(b"\x89PNG") else ".jpg" if image.startswith(b"\xff\xd8") else ".webp"
    pathlib.Path(f"image-{index}{extension}").write_bytes(image)

异步图片与故障排查

开启异步图片任务的部署可用 POST /v1/images/generations/async 或 /v1/images/edits/async,保存返回的 request_id / task_id / id,再用同一 Key 查询 GET /v1/images/tasks/{id}。状态字段、result 与图片 data 以实际响应为准。未开放异步接口时可能返回 404;确认是端点未开放后才改用同步接口,不要把模型不存在等其他 404 当成重试依据。

403 permission_error / Image generation is not enabled for this group:联系管理员开启分组图片权限。400:核对模型、尺寸、图片字段与协议。401:检查 Key。402/403:查看余额、额度与权限。429:按 Retry-After 退避。5xx 或超时:保存 X-Request-Id、时间及脱敏响应,先查任务和用量,不自动重复生成。视频提交、轮询与首帧示例请看 /docs/generate-video。

请求参数

model
必填 string:当前 Key 可用的准确模型 ID。
prompt
string:图片生成或视频 prompt 协议的提示词;使用原生 content 时按渠道要求选择。
size
可选 string:模型支持的图像尺寸。
n
可选 integer:生成数量,以模型限制为准。
quality
可选 string:模型支持的质量档位,不同模型取值不同。
image
可选 object:支持图生图的渠道使用 {url: "https://..."};本地文件编辑另用 multipart /images/edits。

请求示例

示例采用当前目录中的模型 ID。实际可调用范围取决于 API Key 的分组权限,请先查询 GET /v1/models。

cURL
curl -X POST "https://api.hanrouter.ai/v1/images/generations" \
  -H "Authorization: Bearer $HANROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "your-model-id",
  "prompt": "A red bicycle beside a tree"
}'

响应示例

JSON · 结构示例
{
  "data": [
    {
      "url": "https://example.com/generated-image.png"
    }
  ]
}