OpenRouter 入门与概览

OpenRouter 入门与概览

图像生成

6 分钟阅读

图像生成

如何使用 OpenRouter 的专用图像 API 生成图像

OpenRouter 提供专用的图像 API，可根据文本提示词（以及可选的参考图）生成图像。该 API 覆盖模型发现、各端点能力以及生成。你可以在按图像输出筛选的模型页面浏览可用模型和定价。

蓝调时分的当代街区店面，暖白色草书霓虹灯写着 OpenRouter，门口有植物和自行车，灯光映在潮湿的路面上

蓝调时分的当代街区店面建筑摄影，暖光在暮色中柔和发光。入口上方，暖白色手弯霓虹灯以流畅草书精确写着 "OpenRouter"，这是画面中唯一的文字。大玻璃窗内可见温馨、有生活气息的室内：木架上摆着书籍与陶瓷，茂盛的垂吊植物，以及柔和的吊灯。门口放着盆栽和一辆自行车，金色灯光洒在湿漉漉的路面上，形成轻柔的反射。正面构图，材质写实，安静的街道上没有行人。

  • 模型：openai/gpt-image-2
  • 参数：quality: "high"、aspect_ratio: "16:9"、n: 1
  • 输出：1536×864 PNG
  • 生成时间：94 秒
  • 费用：$0.13

在图像演练场（Image Playground）中试用此提示词 →

查找模型

通过图像模型 API

专用的图像模型端点会列出所有可用图像模型及其能力：

curl "https://openrouter.ai/api/v1/images/models"

data 数组中的每条记录包含：

{
  "data": [
    {
      "id": "bytedance-seed/seedream-4.5",
      "name": "Seedream 4.5",
      "description": "A text-to-image model.",
      "created": 1692901234,
      "architecture": {
        "input_modalities": ["text", "image"],
        "output_modalities": ["image"]
      },
      "supported_parameters": {
        "resolution": { "type": "enum", "values": ["1K", "2K", "4K"] },
        "seed": { "type": "boolean" }
      },
      "supports_streaming": false,
      "endpoints": "/api/v1/images/models/bytedance-seed/seedream-4.5/endpoints"
    }
  ]
}
字段说明
id生成请求中使用的模型 slug
architecture模型接受的输入和输出模态
supported_parameters所有端点能力的并集。每个键是请求字段名；值是能力描述符
supports_streaming是否有任一端点支持原生服务器发送事件（SSE）流式传输（stream: true）
endpoints指向该模型完整各端点记录的 URL

各端点记录

同一模型可能由多家模型服务提供商提供。要查看各端点的最终能力、定价和透传选项：

curl "https://openrouter.ai/api/v1/images/models/bytedance-seed/seedream-4.5/endpoints"
{
  "id": "bytedance-seed/seedream-4.5",
  "endpoints": [
    {
      "provider_name": "Bytedance",
      "provider_slug": "bytedance",
      "provider_tag": "bytedance",
      "supported_parameters": {
        "resolution": { "type": "enum", "values": ["1K", "2K", "4K"] },
        "seed": { "type": "boolean" }
      },
      "allowed_passthrough_parameters": [],
      "supports_streaming": false,
      "pricing": [
        { "billable": "output_image", "unit": "image", "cost_usd": 0.05 }
      ]
    }
  ]
}
字段说明
provider_slug用于在 provider.options[slug] 中传入模型服务提供商特定参数
provider_tag用于将请求固定到特定模型服务提供商。当无法进行模型服务提供商级路由时为 null
supported_parameters该端点接受的最终参数集合（模型级并集的子集）
allowed_passthrough_parameters在 provider.options[provider_slug] 下接受的模型服务提供商特定键
supports_streaming该端点是否支持原生 SSE 流式传输
pricing该端点的计费价格项。每条记录包含 billable（例如 output_image、input_image、input_reference）、unit（image、megapixel 或 token）、cost_usd，以及可选的 variant 档位（例如分辨率分档定价中的 2k、4k）

能力描述符

supported_parameters 映射使用带类型的描述符，说明每个请求字段接受什么：

类型形状含义
enum{ type: "enum", values: ["1K", "2K", "4K"] }可接受字符串值的离散允许列表
range{ type: "range", min: 0, max: 100 }[min, max] 范围内的任意整数均有效
boolean{ type: "boolean" }支持（存在）或不支持（不存在）

若某个键不存在，表示该端点不支持该参数。

通过 Models API

你也可以通过通用的 Models API 发现图像模型：

curl "https://openrouter.ai/api/v1/models?output_modalities=image"

在模型页面上

访问模型页面，按输出模态筛选，查找具备图像生成能力的模型。

API 用法

向 /api/v1/images 发送包含模型和提示词的 POST 请求：

Unsupported component: <Template>

import requests
import json

url = "https://openrouter.ai/api/v1/images"
headers = {
    "Authorization": f"Bearer {API_KEY_REF}",
    "Content-Type": "application/json"
}

payload = {
    "model": "{{MODEL}}",
    "prompt": "一只漂浮在太空中的小熊猫宇航员，影棚灯光"
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

for image in result["data"]:
    # image["b64_json"] 包含 Base64 编码的图像
    print(f"已生成图像（{len(image['b64_json'])} 个字符）")

响应格式

图像以 Base64 编码的字节形式返回。usage 字段在可用时报告 Token 计数和费用。

只要能识别格式（包括 image/png），就会出现 media_type 字段；仅在无法确定格式时才会省略：

{
  "created": 1748372400,
  "data": [
    {
      "b64_json": "<base64-encoded-image>",
      "media_type": "image/png"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 4175,
    "total_tokens": 4175,
    "cost": 0.04
  }
}

对于非 PNG 输出（例如 JPEG、WebP，或 Recraft 矢量模型的 SVG），media_type 会反映实际格式：

{
  "created": 1748372400,
  "data": [
    {
      "b64_json": "<base64-encoded-image>",
      "media_type": "image/svg+xml"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 4175,
    "total_tokens": 4175,
    "cost": 0.04
  }
}

图像配置选项

分辨率与宽高比

使用 resolution、aspect_ratio 或便捷简写 size 控制输出尺寸：

{
  "model": "bytedance-seed/seedream-4.5",
  "prompt": "一张风景照片",
  "resolution": "2K",
  "aspect_ratio": "16:9"
}
  • resolution：标准化档位（512、1K、2K、4K）。具体像素尺寸由各模型服务提供商推导。
  • aspect_ratio：标准化比例。传入 auto 可由模型服务提供商自行选择。常见值包括 1:1、16:9、9:16、4:3、3:4、3:2、2:3、4:5、5:4，以及扩展比例如 1:2、2:1、1:4、4:1、1:8、8:1、9:21、21:9。模型服务提供商会将取值限制在其所支持的子集内。请查看模型的 supported_parameters 以了解可接受的值。
  • size：便捷简写。传入档位（"2K"）或明确像素（"2048x2048"），会为该模型服务提供商进行标准化。档位尺寸等价于设置 resolution，并可与 aspect_ratio 组合使用。明确的像素尺寸具有决定性。若同时提供了不匹配的 resolution 或 aspect_ratio，请求会以 400 被拒绝。

查看模型的 supported_parameters，了解各端点接受哪些值。

质量与输出格式

{
  "model": "openai/gpt-image-1",
  "prompt": "一张产品照片",
  "quality": "high",
  "output_format": "png",
  "background": "transparent"
}
  • quality — auto、low、medium 或 high。没有质量调节选项的模型服务提供商会忽略该参数。
  • output_format — png、jpeg、webp 或 svg（仅限矢量化模型；SVG 标记会以 Base64 编码放入 b64_json）。
  • background — auto、transparent 或 opaque。transparent 需要支持透明通道的格式（png 或 webp）。
  • output_compression — webp/jpeg 为 0-100。对 png 忽略。

多张图像

使用 n 每次请求最多 10 张图像：

{
  "model": "openai/gpt-image-1",
  "prompt": "一只可爱的猫",
  "n": 4
}

并非所有模型服务提供商都支持 n > 1。请查看模型的 supported_parameters 以确认是否可用。

图生图（参考图）

通过 input_references 传入参考图以引导生成：

{
  "model": "openai/gpt-image-1",
  "prompt": "把这个场景改成水彩画风格",
  "input_references": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/photo.jpg"
      }
    }
  ]
}

参考图可以是 HTTP(S) URL 或 Base64 Data URL。可接受的参考图数量因模型服务提供商而异。

模型服务提供商路由

当一个模型有多家模型服务提供商时，使用 provider 对象指定可由哪些端点处理该请求：

{
  "model": "google/gemini-2.5-flash-image",
  "prompt": "一只漂浮在太空中的小熊猫宇航员",
  "provider": {
    "only": ["google-ai-studio"],
    "allow_fallbacks": false
  }
}

图像 API 支持以下路由字段：

  • only — 仅允许列出的模型服务提供商 slug。
  • order — 按列出的顺序尝试各模型服务提供商。
  • ignore — 排除列出的模型服务提供商 slug。
  • sort — 按 price、throughput 或 latency 对符合条件的端点排序。
  • allow_fallbacks — 为 false 时，在主模型服务提供商之后停止，不再尝试其他符合条件的模型服务提供商。

使用各端点记录中的 provider_tag 作为基础的模型服务提供商 slug。各 OpenRouter API 共享的路由行为见模型服务提供商路由。

模型服务提供商特定选项

通过 provider.options 传入模型服务提供商特定参数，键名为端点 API 中的模型服务提供商 slug：

{
  "model": "black-forest-labs/flux.2-pro",
  "prompt": "一幅富有戏剧感的肖像",
  "provider": {
    "options": {
      "black-forest-labs": {
        "steps": 40,
        "guidance": 3
      }
    }
  }
}

各端点记录中的 allowed_passthrough_parameters 字段列出可接受的键。

流式图像生成

支持原生 SSE 流式传输（在发现 API 中 supports_streaming: true）的模型可以在生成过程中返回部分图像：

{
  "model": "openai/gpt-image-1",
  "prompt": "一幅细节丰富的风景",
  "stream": true
}

响应为包含三种事件类型的 SSE 流：

部分图像 — 每当有部分渲染结果可用时发出：

data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"<base64>"}

已完成 — 最终图像就绪时发出。只要能识别格式，就会出现 media_type 字段：

data: {"type":"image_generation.completed","b64_json":"<base64>","media_type":"image/png","created":1748372400,"usage":{"prompt_tokens":16,"completion_tokens":272,"total_tokens":288,"cost":0.011}}

对于非 PNG 输出（例如 Recraft 矢量模型的 SVG），media_type 会反映实际格式：

data: {"type":"image_generation.completed","b64_json":"<base64>","media_type":"image/svg+xml","created":1748372400,"usage":{"prompt_tokens":16,"completion_tokens":272,"total_tokens":288,"cost":0.011}}

completed 事件中的 usage 对象包含 cost（美元），形状与缓冲响应一致。

错误 — 若生成在流中途失败则发出：

data: {"type":"error","error":{"message":"Generation failed","code":"server_error"}}

流以 data: [DONE] 结束。

Unsupported component: <Template>

import requests

url = "https://openrouter.ai/api/v1/images"
headers = {
    "Authorization": f"Bearer {API_KEY_REF}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json={
    "model": "openai/gpt-image-1",
    "prompt": "一幅细节丰富的风景画",
    "stream": True
}, stream=True)

for line in response.iter_lines():
    if line:
        decoded = line.decode("utf-8")
        if decoded.startswith("data: ") and decoded != "data: [DONE]":
            import json
            event = json.loads(decoded[6:])
            print(f"事件：{event['type']}")

计费与取消

图像生成的计费是全额或零计费。一次生成要么完成并全额计费，要么失败且不计费 — 不存在部分或按比例的图像计费。这与对话补全不同：在对话补全中，即使取消流式请求，仍会按取消前已产生的 Token 计费。

  • 已完成的生成按该端点的定价对完整图像输出计费。
  • 失败或已取消的生成不计费。当生成未完成时，请求返回 502 Bad Gateway 而非部分结果，且不会记录任何费用。

如果客户端在生成过程中断开连接，上游模型服务提供商仍可能完成图像渲染并向 OpenRouter 收费。但无论何种情况，客户端只会看到两种结果之一：已全额计费的完整结果，或错误。OpenRouter 不会对用户未收到的结果尝试计费。

对于流式请求，流结束前送达的任何部分预览图像都不会产生部分费用。计费取决于最终图像是否完成，因此提前终止的流（客户端断开或流中途出错）的计费方式与失败的生成完全相同：完全不计费。

请求参数

参数类型是否必需说明
modelstring是模型 slug（例如 bytedance-seed/seedream-4.5）
promptstring是所需图像的文本描述
ninteger否要生成的图像数量（1-10）
resolutionstring否分辨率档位（512、1K、2K、4K）
aspect_ratiostring否宽高比（1:1、16:9、9:16、4:3、3:4、1:4、4:1 等）
sizestring否便捷简写 — 档位或明确像素（"2048x2048"）
qualitystring否auto、low、medium 或 high
output_formatstring否png、jpeg、webp 或 svg
backgroundstring否auto、transparent 或 opaque
output_compressioninteger否webp/jpeg 的压缩级别（0-100）
seedinteger否用于确定性生成的种子（在支持的情况下）
streamboolean否通过 SSE 流式传输部分图像
input_referencesarray否用于图生图的参考图
provider.onlystring[]否仅允许这些模型服务提供商 slug
provider.orderstring[]否按此顺序尝试模型服务提供商 slug
provider.ignorestring[]否排除这些模型服务提供商 slug
provider.sortstring or object否按价格、吞吐量或延迟对符合条件的端点排序
provider.allow_fallbacksboolean否当主模型服务提供商失败时，允许改用其他符合条件的模型服务提供商
provider.optionsobject否以模型服务提供商 slug 为键的特定参数

使用图像模型 API查看各模型和端点支持哪些参数。

上一页多模态概览下一页 视频生成