开发者

接口文档

提供 OpenAI 风格的图像接口。设置 base_url 与 api_key 后，请使用本站模型 ID 和下列支持的参数；图片响应目前仅支持 URL。

创建 API Key 查看可用模型

基础信息

认证与 Base URL

Base URL: https://incircles.cc/v1
Authorization: Bearer sk-your-circles-key

还没有 Key？去设置生成

端点

一个 API，覆盖完整创作链路

GET/v1/modelsPOST/v1/images/generationsPOST/v1/videos

计费与队列

按模型配置透明计费

任务创建前冻结积分，成功后结算，确认失败自动返还。图像全局并发 10，Bonanza 通道并发 10，单次 n 仍按模型卡片的张数上限校验。

202 异步402 余额不足429 限流

LIVE CATALOG

可用模型

以下数据直接读取当前后台已启用的模型配置，与 GET /v1/models 返回的公开字段保持一致。模型、价格和能力变更后会自动更新。

模型	类型	积分定价	能力
Image2`image2`标准图像模型	图片	Low-1k/2k/4k 同价-官方渠道3 积分	1K1:12K1:14K1:1支持图生图最多 4 张
monalisa-v1`bonanzagen-mu465kn7`标准图像模型	图片	自研文生图-v13 积分	1:11:13:23:216:916:92:32:39:169:16仅文生图最多 1 张

ENDPOINTS

接口一览

所有请求都需要携带个人 API Key。请求路径已包含 /v1 前缀。

方法	路径	用途
GET	`/v1/models`	读取当前开放的图片、编辑和视频模型
POST	`/v1/images/generations`	OpenAI Images 风格图片生成
POST	`/v1/images/edits`	multipart 图片编辑与参考图
GET	`/v1/images/jobs/{id}`	查询异步图片任务

REQUEST PARAMETERS

参数说明

参数值必须来自对应模型卡片。省略档位或分辨率时，服务端使用该模型的第一个可用值。

文生图 `/v1/images/generations`

参数	类型	要求	说明
`model`	string	必填	模型 ID，使用上方可用模型中的值
`prompt`	string	必填	1–16000 字符的文字描述
`quality`	string	可选	模型档位 ID，省略时使用第一档
`size`	string	可选	分辨率 ID，省略时使用第一档
`n`	integer	可选	生成数量，默认 1，不超过模型上限
`response_format`	string	可选	当前仅支持 url

图像编辑 `/v1/images/edits · multipart`

参数	类型	要求	说明
`image`	file	必填	PNG、JPG 或 WEBP，单张不超过 8 MB
`prompt`	string	必填	编辑或参考描述
`model`	string	必填	必须支持图像编辑的模型 ID
`quality / size`	string	可选	从模型卡片选择有效的档位与分辨率

SIZE REFERENCE

分辨率与比例

size 使用模型返回的公开 ID，同时决定比例与计费档位。不同模型的尺寸不强行统一，下面只列当前实际开放的值。

Image2 `image2`

公开 ID	比例
`1k`	1:1
`2k`	1:1
`4k`	1:1

monalisa-v1 `bonanzagen-mu465kn7`

公开 ID	比例
`1:1`	1:1
`3:2`	3:2
`16:9`	16:9
`2:3`	2:3
`9:16`	9:16

QUICKSTART

调用示例

下面的示例会自动填入当前第一个可用模型的真实 ID。生产环境请从 /v1/models 动态读取模型和参数。视频示例仅在站点开放视频模型时显示。

图片生成 · curl

curl $CIRCLES_API_BASE/images/generations \
  -H "Authorization: Bearer $CIRCLES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "image2",
    "prompt": "雨后的城市街角，电影感摄影",
    "quality": "low",
    "size": "1k",
    "n": 1,
    "response_format": "url"
  }'

图像编辑 · multipart

curl $CIRCLES_API_BASE/images/edits \
  -H "Authorization: Bearer $CIRCLES_API_KEY" \
  -F "model=image2" -F "quality=low" \
  -F "size=1k" -F "image=@input.png" \
  -F 'prompt=把背景改成安静的海边'

列出模型 · curl

curl $CIRCLES_API_BASE/models \
  -H "Authorization: Bearer $CIRCLES_API_KEY"

查询视频任务 · curl

curl $CIRCLES_API_BASE/videos   -H "Authorization: Bearer $CIRCLES_API_KEY"

RESPONSE

响应与任务状态

图片生成和编辑均支持 Prefer: respond-async：立即返回 202 与任务 ID，通过 GET /v1/images/jobs/{id} 查询。未使用此请求头时会等待结果，超过等待窗口同样返回 202。成功响应为 {"created": 0, "data": [{"url": "..."}]}。

queued→in_progress→completed

每次新任务发送一个 8–200 字符的 Idempotency-Key；断线重试须沿用相同 Key 和参数（编辑还须使用相同图片），请勿生成新 Key。Key 在 24 小时内可重放；review 表示结果待核对、积分仍冻结。未发布图片仅保留约 30 分钟，请完成后及时下载；已发布到广场的作品不受此临时保留期影响。视频完成后使用 /content 下载。

ERRORS

错误码

400 参数错误401 认证无效402 积分不足403 功能未开放404 模型或任务不存在409 请求编号冲突410 图片或请求记录已过期429 触发限流502 服务处理失败

错误格式统一为 {"error":{"message":"…","type":"…","code":"…"}}。429 响应附带 Retry-After。