API

我的 API:异步生图接口

推荐外部工具、脚本和朋友使用异步接口:先提交任务,立刻拿到 task_id poll_url,再轮询结果。 同步接口 /v1/images/generations 会等真实生图完成,客户端容易超时,不建议作为对外主接口。

完整 Markdown 文档: https://img.2capi.com/api.md

Markdown 文档

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。