图像生成 · MossHub API 文档

图片模型沿用各自的官方接口：OpenAI Images、火山方舟图片与 Gemini，结果随响应同步返回。

选择端点

每个图片模型走它自己的官方接口，请求体和响应都沿用官方格式。MossHub 只把模型 ID 换成上游模型，其余字段原样转发，响应也原样返回。模型走哪个端点，见控制台「模型」详情的「接入」；用错端点返回 400。

接口	端点
OpenAI Images	`POST /v1/images/generations`，编辑图片用 `POST /v1/images/edits`
火山方舟图片	`POST /ark/api/v3/images/generations`
Gemini	`POST /v1beta/models/{model}:generateContent`

请求头带 Authorization: Bearer <API 密钥>，也可以改用 x-goog-api-key: <API 密钥>（Gemini 的写法）。图片生成是同步的，结果在同一个响应里返回。

OpenAI Images

POST /v1/images/generations
Authorization: Bearer $MOSSHUB_API_KEY
Content-Type: application/json

{ "model": "YOUR_MODEL_ID", "prompt": "一只在雨中打伞的橘猫" }

图片以 base64 放在 data[].b64_json，usage 是计费依据：

{
  "created": 1785125529,
  "data": [{ "b64_json": "iVBORw0KGgo…" }],
  "usage": {
    "input_tokens": 14,
    "input_tokens_details": { "text_tokens": 14, "image_tokens": 0 },
    "output_tokens": 196,
    "output_tokens_details": { "text_tokens": 0, "image_tokens": 196 }
  }
}

/v1/images/edits 接受 multipart/form-data 或 JSON，参考图的写法见输入素材。

火山方舟图片

POST /ark/api/v3/images/generations
Authorization: Bearer $MOSSHUB_API_KEY
Content-Type: application/json

{ "model": "YOUR_MODEL_ID", "prompt": "一只在雨中打伞的橘猫" }

图片在 data[].url 或 data[].b64_json，尺寸在 data[].size；usage.generated_images 与 usage.input_images 是计费依据。

Gemini

模型 ID 写在路径里：

POST /v1beta/models/YOUR_MODEL_ID:generateContent
x-goog-api-key: $MOSSHUB_API_KEY
Content-Type: application/json

{
  "contents": [{ "parts": [{ "text": "一只在雨中打伞的橘猫" }] }],
  "generationConfig": { "responseModalities": ["TEXT", "IMAGE"] }
}

只支持 generateContent，streamGenerateContent 等方法返回 400。URL 查询参数不会转发，密钥要放在请求头里。

MossHub 拒绝的请求

下列请求不会发给上游，直接返回 400：

要求流式：stream 为 true，表单字段同样适用；
带 tools，或开启火山方舟的 layer_decomposition；
引用存放在上游的文件，如 file_id、asset:// 地址、Gemini 的 fileData，改法见输入素材；
请求体不是 JSON 对象或合法表单、缺少 model（Gemini 写在路径里），或 JSON 重复了同一个顶层字段。

请求体最多 32 MiB，超出返回 413。客户端断开后，已发出的生成仍会完成并计费，请把超时设得足够长。

计费

接口	计量
OpenAI Images	`usage` 里的输入文本、输入图片、输出文本和输出图片 token
火山方舟图片	输出图片张数和输入图片张数；价格可按输出图片的像素分档
Gemini	`usageMetadata` 里的输入、文本输出、思考和图片输出 token

单价见控制台模型详情的「价格」。

常见失败

状态	原因
400	端点不对、被上面的规则拒绝，或上游认为参数不对
401	密钥无效或已过期
402	额度已用完
403	这把密钥不能使用该模型
404	模型不存在
413	请求体超过 32 MiB
429	线路繁忙，按 `Retry-After` 等待
502 / 503 / 504	上游出错、暂无可用线路或上游超时

错误体沿用各接口的官方格式，见错误处理。

完整调用示例

先替换密钥、授权模型 ID 与示例输入；不自动执行。

curl -sS "$MOSSHUB_API_BASE/v1/images/generations" \
  -H "Authorization: Bearer $MOSSHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"YOUR_MODEL_ID","prompt":"一只在雨中打伞的橘猫"}' \
  | python3 -c 'import base64, json, sys
reply = json.load(sys.stdin)
if "data" not in reply:
    sys.exit(json.dumps(reply, ensure_ascii=False))
open("image.png", "wb").write(base64.b64decode(reply["data"][0]["b64_json"]))
print("已保存 image.png")'