v0.1.0
v0.1.0
API
我的 API:异步生图接口
推荐外部工具、脚本和朋友使用异步接口:先提交任务,立刻拿到 task_id 和 poll_url,再轮询结果。 同步接口 /v1/images/generations 会等真实生图完成,客户端容易超时,不建议作为对外主接口。
完整 Markdown 文档: https://img.2capi.com/api.md
API Key 管理
正在读取 API Key
调用流程与示例
1. 生成 API Key
在本页点击生成并复制。调用方只需要 Authorization: Bearer <API Key>。
2. 提交异步任务
POST /api/image-tasks/generations,返回 queued/running 任务和 poll_url,不等待真实生图完成。
3. 轮询任务结果
GET /api/image-tasks?ids=<task_id>,直到 status 变成 succeeded、failed 或 cancelled。
提交任务 curl
把 c2a_xxx 换成你的 API Key。
curl -X POST "https://img.2capi.com/api/image-tasks/generations" \
-H "Authorization: Bearer c2a_xxx" \
-H "Content-Type: application/json" \
-d '{
"client_task_id": "demo-image-001",
"prompt": "请生成一张图片:一只橘猫坐在月光窗台上,水彩风格,只输出图片。",
"model": "gpt-image-2-5.5",
"n": 1
}'轮询结果 curl
轮询间隔建议 3-8 秒,直到进入终态。
curl -X GET "https://img.2capi.com/api/image-tasks?ids=demo-image-001" \
-H "Authorization: Bearer c2a_xxx"图生图 JSON curl
传 image_base64,接口会先上传参考图再提交异步任务。
curl -X POST "https://img.2capi.com/api/image-tasks/generations" \
-H "Authorization: Bearer c2a_xxx" \
-H "Content-Type: application/json" \
-d '{
"client_task_id": "demo-edit-001",
"prompt": "请生成一张图片:参考这张图,改成赛博朋克夜景风格,只输出图片。",
"model": "gpt-image-2-5.5",
"n": 1,
"image_base64": "iVBORw0KGgo..."
}'编辑图 multipart curl
适合直接上传本地 reference.png,提交后仍用 poll_url 轮询。
curl -X POST "https://img.2capi.com/api/image-tasks/edits" \
-H "Authorization: Bearer c2a_xxx" \
-F "client_task_id=demo-edit-002" \
-F "prompt=请生成一张图片:把参考图改成水彩插画风格,只输出图片" \
-F "model=gpt-image-2-5.5" \
-F "n=1" \
-F "image=@reference.png"高清 2K/4K curl
加 size 控制宽高比、resolution 控制清晰度,2K/4K 仅高级用户。
curl -X POST "https://img.2capi.com/api/image-tasks/generations" \
-H "Authorization: Bearer c2a_xxx" \
-H "Content-Type: application/json" \
-d '{
"client_task_id": "demo-hd-001",
"prompt": "请生成一张图片:雪山日出,超广角风光大片,只输出图片。",
"model": "gpt-image-2-5.5",
"n": 1,
"size": "16:9",
"resolution": "2k"
}'宽高比与清晰度(size / resolution)
- size(宽高比):留空自动;可选 1:1、16:9、9:16、4:3、3:4,兼容 1024x1024 等写法。
- resolution(清晰度):留空或 1k 为标准;2k、4k 为高清。
- 2K/4K 走高清通道,仅高级用户可用;普通用户提交返回 403 premium_required。
- 1K 通过提示词控制比例;2K/4K 按精确像素输出。
提交返回示例
{
"task_id": "demo-image-001",
"poll_url": "/api/image-tasks?ids=demo-image-001",
"task": {
"id": "demo-image-001",
"status": "queued",
"model": "gpt-image-2-5.5",
"n": 1
}
}成功轮询返回示例
{
"items": [
{
"id": "demo-image-001",
"status": "succeeded",
"conversation_id": "69f...",
"message_id": "msg...",
"session_id": "sid...",
"result": {
"data": [
{
"b64_json": "...",
"file_id": "sed:file_xxx"
}
]
},
"gallery_task": {
"public_image_id": "img_xxx",
"image_url_public": "https://img.2capi.com/api/public/images/img_xxx.png"
}
}
]
}Python 完整示例(提交 + 轮询 + 保存)
纯标准库,替换 API_KEY 后可直接运行。
from __future__ import annotations
import base64
import json
import time
import urllib.error
import urllib.request
BASE_URL = "https://img.2capi.com"
API_KEY = "c2a_xxx" # 替换成你的固定 API Key / Replace with your API key
MODEL = "gpt-image-2-5.5"
PROMPT = "请生成一张图片:一只橘猫坐在月光窗台上,水彩风格,只输出图片。"
TASK_ID = f"api_demo_{int(time.time())}"
if not API_KEY or API_KEY == "c2a_xxx":
raise SystemExit("请先把 API_KEY 替换成你的 c2a_xxx 固定 Key")
def request_json(method: str, path: str, body: dict | None = None) -> dict:
data = None if body is None else json.dumps(body, ensure_ascii=False).encode("utf-8")
headers = {"Accept": "application/json", "Authorization": f"Bearer {API_KEY}"}
if body is not None:
headers["Content-Type"] = "application/json"
request = urllib.request.Request(BASE_URL + path, data=data, headers=headers, method=method)
try:
with urllib.request.urlopen(request, timeout=60) as response:
return json.loads(response.read().decode("utf-8") or "{}")
except urllib.error.HTTPError as exc:
raw = exc.read().decode("utf-8", errors="replace")
if exc.code == 429 and "image_task_limited" in raw:
raise SystemExit("当前固定 Key 所属用户已有图片任务处理中,请等待上一个任务完成后重试。") from exc
raise RuntimeError(f"HTTP {exc.code}: {raw}") from exc
submit = request_json(
"POST",
"/api/image-tasks/generations",
{
"client_task_id": TASK_ID,
"prompt": PROMPT,
"model": MODEL,
"n": 1,
},
)
poll_url = submit.get("poll_url") or f"/api/image-tasks?ids={TASK_ID}"
print("submitted:", json.dumps(submit, ensure_ascii=False))
deadline = time.time() + 360
task = {}
while time.time() < deadline:
result = request_json("GET", poll_url)
items = result.get("items") or []
task = items[0] if items else {}
status = task.get("status")
print("status:", status)
if status in {"succeeded", "failed", "cancelled"}:
break
time.sleep(6)
if task.get("status") != "succeeded":
raise SystemExit(f"任务失败:{json.dumps(task, ensure_ascii=False)}")
image = ((task.get("result") or {}).get("data") or [{}])[0]
with open("async_image_result.png", "wb") as file:
file.write(base64.b64decode(image.get("b64_json") or ""))
print("saved:", "async_image_result.png")
gallery_task = task.get("gallery_task") or {}
print("gallery_image_url:", gallery_task.get("image_url_public"))
print("说明:优先读 image_url_public,公开图片地址可重复访问,不暴露 API Key。")接口调用说明
推荐外部调用方使用固定 API Key 调用异步接口。/v1/images/generations 是同步兼容接口,会等上游真实生图和图片下载都完成后才返回;图片任务常常需要几十秒到数分钟,Apifox、网关或客户端可能超时。异步接口提交后立即返回任务 ID,更适合外部调用。轮询成功后优先读取 gallery_task.image_url_public,这是基于公开图片 ID 的可直接访问图片 URL,不暴露 API Key,也不限制只访问一次。
常用字段和错误
- 模型:gpt-image-2 或 gpt-image-2-5.5。
- 数量:n 支持 1-4;带参考图或续图时建议 n=1。
- 宽高比 size:留空自动,可选 1:1 / 16:9 / 9:16 / 4:3 / 3:4。
- 清晰度 resolution:留空或 1k 标准;2k / 4k 高清,仅高级用户。
- 400:size 或 resolution 非法(image_size_invalid / image_resolution_invalid)。
- 401:Authorization 缺失或 API Key 错误。
- 403:2K/4K 需高级用户(premium_required)。
- 429:用户并发或每分钟提交次数达到限制。
- 502:上游生成失败,查看 error_code 和 upstream_status。