图片生成与编辑

与 OpenAI Images 接口兼容。不走对话协议——它是独立的图片端点，按张计费，没有流式返回。

POST https://www.apigoto.com/v1/images/generations

POST https://www.apigoto.com/v1/images/edits

两个端点的区别

	generations	edits
用途	纯文本生图	基于已有图片改图 / 局部重绘
Content-Type	application/json	multipart/form-data
必带	`model` + `prompt`	`model` + `prompt` + `image` 文件

💡

两种请求体网关都认得

网关从 JSON 里取 model 字段，也会从 multipart 表单里取 model 字段。无论哪种格式，model 都是必填的，缺了直接返回 40002，不会进上游。

请求头

Authorizationstring必填

Bearer sk-rouertcode-…。此端点同样只读这一个鉴权头。

Rc-App-Idstring可选

来源应用标识，会记入调用日志。不填时按 User-Agent 自动识别。

Rc-Custom-Idstring可选

自定义业务标识，会写入调用日志，便于你按自己的业务维度对账。

请求参数

modelstring必填

支持图片生成的平台模型 ID。可在定价接口里按 support_features 含 image 筛选。

promptstring必填

图片描述。

imagefileedits 必填

待编辑的原图，multipart 文件字段。

maskfile可选

遮罩图，透明区域表示要重绘的部分。仅 edits 使用。

ninteger可选

生成张数，默认 1。按张计费，改这个值直接影响费用。

sizestring可选

尺寸，如 1024x1024。可选值取决于具体模型。

quality / style / backgroundstring可选

上游模型的画质与风格控制。支持哪些取值由上游决定，网关原样转发。

response_formatstring可选

url 或 b64_json。部分模型只支持其中一种，返回哪种以实际响应为准。

响应

200 OK

{
  "created": 1755500000,
  "data": [
    { "url": "https://.../generated-image.png" }
  ]
}

⏳

返回的 URL 是有时效的

上游返回的图片链接通常在几十分钟到几小时内失效。 需要长期保存就立刻下载转存到自己的存储，别把这个 URL 直接写进数据库当永久地址。

调用示例

generations.sh

curl https://www.apigoto.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $APIGOTO_API_KEY" \
  -d '{
    "model": "your-image-model",
    "prompt": "一只坐在窗台上的橘猫，水彩风格",
    "n": 1,
    "size": "1024x1024"
  }'

edits.sh

# 不要手写 Content-Type，让 curl 自己带 boundary
curl https://www.apigoto.com/v1/images/edits \
  -H "Authorization: Bearer $APIGOTO_API_KEY" \
  -F "model=your-image-model" \
  -F "prompt=把背景换成夜晚的星空" \
  -F "image=@cat.png" \
  -F "mask=@cat-mask.png"

images.py

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://www.apigoto.com/v1",
    api_key=os.environ["APIGOTO_API_KEY"],
)

resp = client.images.generate(
    model="your-image-model",
    prompt="一只坐在窗台上的橘猫，水彩风格",
    n=1,
    size="1024x1024",
)
print(resp.data[0].url)

⚠️

示例里的 your-image-model 是占位符

请以模型列表里的实际 model_id 为准。写不存在的模型名会返回 50201 no available upstream for this model。

限流与计费

图片有独立的限流维度。策略里的「图片张数」与请求次数、Token 各自独立计窗，锚点也是独立的——见限流、配额与并发。
超限返回 42902。图片维度没有专属错误码， message 是 rpm limit exceeded，别被误导。
按张计价，不按 token。价格取 image_price，倍率链与对话调用一致，见计费、积分与订阅。
n 越大费用越高。批量生成前先估算。

可能的错误

HTTP	code	原因
400	40002	请求体里没有 `model`（JSON 与 multipart 都会查）
400	40003	请求体为空或读取失败
401	40001	没有 `Authorization: Bearer`
413	41301	上传的图片让请求体超过 100 MiB
429	42902	图片张数限额用尽
502	50201	模型名写错，或该模型没有可用上游

完整清单见错误码总表。