图片生成 API

概述

该接口把文本提示词变成一张图片，并以 Base64 JSON 同步返回。

它遵循平台的付款流程：匿名 x402 不需要账号，平台 API Key 使用发放给你 Koinelix 账号的额度。

付款流程、认证方式和通用错误见平台文档。 →

快速开始

先发一个普通请求查看报价，再让 x402 客户端付款并保存图片。

# 1. Ask for a quote. No payment, no account.
curl -i -X POST https://api.koinelix.com/v1/images/generations \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"A watercolor lighthouse at sunrise","size":"1024x1024","output_format":"png"}'

# HTTP/2 402
# PAYMENT-REQUIRED: <base64 x402 v2 quote: price, network, asset, payee>
#
# 2. An x402 client signs that quote with your wallet and repeats the same request
#    with a PAYMENT-SIGNATURE header. See the TypeScript and Python tabs.

• x402 调用无需账号，也无需 API Key。
• 完成付费调用需要一个持有 Base 上 USDC 的钱包。请把私钥放在环境变量里，不要写进代码。
• 生成是同步的，请保持连接直到响应返回。

接口地址

所有请求使用同一个接口。GET 与 HEAD 返回与未签名 POST 相同的 402 报价，供目录平台探测。

POST https://api.koinelix.com/v1/images/generations

请求体

发送一个 JSON 对象。未知字段会被拒绝。

请求示例

{
  "prompt": "A watercolor lighthouse at sunrise",
  "size": "1024x1024",
  "output_format": "png"
}

响应

调用成功返回 200 和 JSON。图片字节保持供应商返回的原样，不做转换。

行为与限制

• 每次调用一张图片（n = 1），不支持流式。
• 请求是同步的，通常需要几十秒。请保持连接直到响应返回。
• 每次付款只买一次生成机会。付款在生成开始前结算，生成失败不退款。
• 你请求的尺寸会转发给图片供应商。返回图片的尺寸可能不同，请以收到的图片为准。
• 图片不会被保存。如果图片已生成但没有送达你，用同一个请求和同一个 PAYMENT-SIGNATURE 重发会返回 image_result_unavailable，不会重新生成。
• 按 IP 地址和付款人限流。提示词最多 6000 个 UTF-8 字节。

错误

以下错误码是图片生成特有的。通用的付款与请求错误见平台文档。