文档

Koinelix 平台

面向 AI Agent 的按次付费 API。所有服务共用一套付款流程，会为其中一个付款的 Agent 就能调用全部服务。

概述

Koinelix 发布供 Agent 和开发者通过 HTTP 调用的 API。每次调用用 x402 协议在 Base 上以 USDC 付费：无需注册，也无需 API Key。

每个服务都有机器可读的说明文档，Agent 可以自行找到接口地址、价格和付款信息。有账号的用户也可以改用平台 API Key，额度由 Koinelix 发放。

平台上的服务。后续会陆续增加，并出现在这里和发现文档中。

服务	用途	状态
图片生成	一次 HTTP 请求，把文字提示词变成图片。	—

更多服务即将到来。

所有付费接口遵循同一个流程。

不要发送 Authorization 头。未签名的请求在读取请求体之前就返回带报价的 402。已签名的请求先校验，再验证并结算。每个新的付款授权只买一次尝试，不退款、不重试。

发送 Authorization: Bearer <key> 和唯一的 Idempotency-Key。优先使用额度；没有额度时返回 402 报价。一次付款最多允许三次尝试。携带但无效的 Key 返回 401，不会被当作匿名调用。

如果签名之后连接中断，请不要再次付款。用同一个请求体和同一个 PAYMENT-SIGNATURE 头重发，接口会返回原请求的状态，不会重复扣款。

已完成的结果是否还能返回，取决于具体服务；每个服务页面会写明。

错误的格式为 { "error": { "code", "message" } }。请根据 code 判断，而不是 message。这些错误码适用于所有付费服务；各服务页面另列自己的错误码。遇到不认识的错误码时，请按 HTTP 状态码处理。

HTTP	错误码	含义
400	`validation_failed`	请求无效，message 会指出问题；已签名的付款不会被验证或结算。
400	`price_not_configured`	尚未配置价格，无法生成报价。
401	`invalid_api_key`	带有 Authorization 头，但 Key 缺失或无效。
402	`payment_required`	尚未付款。PAYMENT-REQUIRED 头里是报价。
402	`payment_invalid`	PAYMENT-SIGNATURE 头无效。
402	`payment_quote_mismatch`	签名之后价格发生了变化，请重新获取报价。
402	`settlement_failed`	付款未结算，你没有被扣款。请重新获取报价后再试。
405	`method_not_allowed`	请使用 POST。GET 与 HEAD 只用于报价探测，不接受付款。
409	`payment_authorization_conflict`	该付款授权已属于另一个请求。
409	`payment_reuse_conflict`	该授权不能用于另一个不同的请求。
409	`attempt_in_progress`	这次付款对应的尝试仍在运行，请稍后用同一请求重试。
415	`unsupported_media_type`	请发送 Content-Type: application/json。
429	`rate_limited`	请求过多，请等待 Retry-After 指定的秒数。
503	`payment_unavailable`	付款验证或结算暂时不可用，没有扣款。
503	`service_paused`	服务已暂停或尚未开放，没有扣款。

服务开放后，API 域名会提供机器可读的说明文档。