图像生成

POST /v1/images/generations —— 由一段文字提示词生成图片，同步返回。

这个接口做什么#

提交一段文字提示词，返回一张或多张图片。整个过程是一次普通的 HTTP 往返：发出请求，等待模型完成绘制，响应中直接带回结果。没有任务 ID，也不需要轮询——那是视频生成才有的形态，因为视频需要数分钟才能完成。

出图通常需要 10 至 60 秒，n 调大后耗时更长。客户端超时应至少设置为 120 秒，否则可能在图片已经生成、费用已经产生的情况下中断连接。

最小可用请求

bash

curl https://ogrouter.ai/v1/images/generations \  -H "Authorization: Bearer $AIROUTER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "openai/dall-e-3",    "prompt": "一只戴着圆眼镜的柴犬，水彩风格，白色背景"  }'

响应：默认给的是链接，不是图片本体

json

{  "created": 1754126400,  "data": [    {      "url": "https://upstream.example.com/img/abc123.png",      "revised_prompt": "A shiba inu wearing round glasses, watercolour style, white background"    }  ]}

请求字段#

modelstring必填: 模型名。支持别名、:变体 与逗号降级链，语法见模型与路由。
promptstring必填: 文字提示词，至少一个字符。
ninteger: 出图张数，取值 1 至 10，默认 1。超出范围返回 invalid_request，不会静默钳到 10 张后按 10 张计费。
sizestring: 形如 1024x1024。平台只校验「宽x高」这一形状，不校验具体取值；可选尺寸随模型而异，取值非法时由上游返回错误。
quality / style / backgroundstring: 原样透传给上游，平台不校验其取值。各家可选值不同，请以所选模型的上游文档为准。
response_formatstring: url（默认）或 b64_json。见下一节，这个选择影响的不只是数据形态。
userstring: 调用方自定义的终端用户标识，透传给上游用于滥用检测。与计费无关。
providerobject: 路由偏好（本平台扩展）：指定线路、排序、价格上限等，语义与对话端点完全一致，见模型与路由。

能力边界#

同步接口：一次 HTTP 往返拿结果，没有任务 ID；长耗时请把客户端超时设到 ≥120 秒。
n 支持 1–10，超出返回 invalid_request（不会静默夹紧后按 10 张收费）。
response_format：url（默认，上游托管链接，有有效期）或 b64_json（本体透传）。
quality / style / background 原样透传上游；size 只校验 宽x高 形态。
模型须在目录中声明 image 模态；provider 的语义与对话端点一致。
限流只计 RPM，不计 TPM（图像没有 token）。

url 还是 b64_json#

该选择需要在发起请求前确定，因为它决定了图片的可获取时长。两种形态平台都原样透传，不做转换。

取值	拿到什么	代价
`url`（默认）	一个指向上游存储的链接	链接具有有效期，各家从数小时到数天不等。过期后平台亦无法找回
`b64_json`	Base64 编码的图片本体	响应体积大一个数量级，但拿到就是最终产物

使用 url 时请立即转存

该链接指向上游存储而非本平台，且存在有效期。链接过期后无法找回，只有账单会留下。请使用 b64_json，或在收到响应的同一处理流程中立即下载并转存到自己的对象存储。

Python：拿到就存，不要把链接直接写进数据库

python

import os, requestsfrom openai import OpenAI
client = OpenAI(api_key=os.environ["AIROUTER_API_KEY"], base_url="https://ogrouter.ai/v1")
result = client.images.generate(    model="openai/dall-e-3",    prompt="一只戴着圆眼镜的柴犬，水彩风格，白色背景",    size="1024x1024",    timeout=180,)
# 上游链接会过期，所以立刻取回本体再落自己的存储image_bytes = requests.get(result.data[0].url, timeout=60).contentwith open("shiba.png", "wb") as f:    f.write(image_bytes)

Node.js：直接要图片本体，省掉一次下载

javascript

import OpenAI from 'openai';import { writeFile } from 'node:fs/promises';
const client = new OpenAI({  apiKey: process.env.AIROUTER_API_KEY,  baseURL: 'https://ogrouter.ai/v1',  timeout: 180_000,});
const result = await client.images.generate({  model: 'openai/dall-e-3',  prompt: '一只戴着圆眼镜的柴犬，水彩风格，白色背景',  response_format: 'b64_json',});
await writeFile('shiba.png', Buffer.from(result.data[0].b64_json, 'base64'));

Java：直接要图片本体，省掉一次下载

java

import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.nio.file.Files;import java.nio.file.Path;import java.time.Duration;import java.util.Base64;import com.fasterxml.jackson.databind.ObjectMapper;
// 上游链接会过期，所以请求时直接要本体String body = """    {      "model": "openai/dall-e-3",      "prompt": "一只戴着圆眼镜的柴犬，水彩风格，白色背景",      "response_format": "b64_json"    }    """;
HttpResponse<String> response = HttpClient.newHttpClient().send(    HttpRequest.newBuilder(URI.create("https://ogrouter.ai/v1/images/generations"))        .header("Authorization", "Bearer " + System.getenv("AIROUTER_API_KEY"))        .header("Content-Type", "application/json")        .timeout(Duration.ofSeconds(180))        .POST(HttpRequest.BodyPublishers.ofString(body))        .build(),    HttpResponse.BodyHandlers.ofString());
String b64 = new ObjectMapper().readTree(response.body())    .get("data").get(0).get("b64_json").asText();Files.write(Path.of("shiba.png"), Base64.getDecoder().decode(b64));

提示词改写#

部分模型（DALL·E 3 是典型）会先对提示词进行重写，再据此生成图片。改写后的文本在 revised_prompt 字段中给出。

当出图结果与预期不符时，应首先查看该字段——它往往是唯一的解释。将提示词写得更具体、歧义更少可以减少改写幅度，但无法完全关闭这一行为。

计费与空结果#

按实际返回的图片张数计费，不是按请求里的 n（上游可能因审核少出几张）。

一张都没返回时走零完成保险：本次不计费，并以 empty_completion 报错，而不是 200 + 空数组（避免重试逻辑误判成功）。

完整规则见计费口径。