图像生成

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

这个接口做什么#

你发一段文字（提示词），拿回一张或几张图。整个过程是一次普通的 HTTP 往返：请求发出去，等模型画完，响应里带着结果。没有任务 ID，也不需要轮询——那是视频生成才有的形态，因为视频要跑几分钟。

出图通常要 10 到 60 秒，n 调大还会更久。客户端超时至少设到 120 秒，否则你会在图已经画好、费用已经产生的时候把连接断掉。

最小可用请求

bash

curl https://ai.oceango.hk/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 而不是夹到边界——夹紧意味着你要 20 张、我们出 10 张还照收 10 张的钱，而你要等看到结果才知道。
sizestring: 形如 1024x1024。我们只校验"宽x高"这个形状，不校验具体取值：可选尺寸随模型而异且经常变，硬编码一张表会在上游加新尺寸的当天误拦合法请求。取值非法时由上游报错。
quality / style / backgroundstring: 原样透传给上游，取值我们不校验——各家的枚举不统一，代为校验只会挡住合法请求。
response_formatstring: url（默认）或 b64_json。见下一节，这个选择影响的不只是数据形态。
userstring: 你自己的终端用户标识，透传给上游做滥用检测。与计费无关。
providerobject: 路由偏好（本平台扩展）：指定线路、排序、价格上限等，语义与对话端点完全一致，见模型与路由。

url 还是 b64_json#

这是发起请求前就要想清楚的一件事，因为它决定了图片能活多久。两种形态我方都原样透传，不做转换。

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

用 url 的话，请立刻转存

那个链接指向的是上游的存储，不是我们的。等你的用户几天后回来点开时它多半已经 404，而那时你只剩账单。要么用 b64_json，要么在收到响应的同一个函数里就把图片下载并存进自己的对象存储。

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

python

import os, requestsfrom openai import OpenAI
client = OpenAI(api_key=os.environ["AIROUTER_API_KEY"], base_url="https://ai.oceango.hk/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://ai.oceango.hk/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'));

提示词被改写了#

部分模型（DALL·E 3 是典型）会先把你的提示词重写一遍再去画。改写后的文本在 revised_prompt 里。

出图和你写的不一样时，先看这个字段——它往往就是唯一的解释。想减少改写幅度，可以把提示词写得更具体、更少歧义，但无法完全关掉。

计费与空结果#

按实际返回的图片张数计费，不是按请求里的 n：上游可能因为内容审核少出几张，你不该为没拿到的图付钱。

一张都没出的时候，我方走零完成保险，这一次不计费，并以 empty_completion 报错，而不是回一个 200 加空数组。返回 200 空列表会让重试逻辑以为成功了，从而静默丢掉这次请求。

完整口径见计费口径。