开发者 API 文档

通过 RESTful API 把 OneCamera 的 AI 图像生成能力集成到你的应用里,OpenAI 兼容协议,几行代码即可上手。

1. 申请 API Key

登录账号后,进入 用户中心 → API 访问,点击「创建新 Key」即可。Key 格式如下:

2. 鉴权

所有 /v1/* 端点都需要在 HTTP 头中携带 Bearer Token:

Authorization: Bearer oc_live_4f8a2b1c9d3e7f6a5b8c1d2e3f4a5b6c

3. 接口列表

文生图 — 输入提示词,返回 AI 生成的图片 URL 或 Base64。OpenAI /v1/images/generations 兼容。

参数	类型	必填	说明
prompt	string	✓	提示词,最多 4000 字符
model	string		模型名:gpt-image-2 / gpt-image-1 / dall-e-3 / 火山方舟模型
size	string		分辨率:512x512 / 1024x1024 / 1024x1536 / 1792x1024
quality	string		auto / low / medium / high
n	integer		生成数量,1-4,默认 1
response_format	string		url 或 b64_json,默认 url

# 1. 登录获取 session
curl -X POST https://imageai.19k.xin/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@ex.com","password":"xxx"}' \
  -c cookies.txt

# 2. 申请 API Key
curl -X POST https://imageai.19k.xin/api/auth/api-keys \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"name":"MyApp Production"}'

# 响应(仅此一次返回完整 key)
{
  "ok": true,
  "warning": "请立即保存此 key,系统不会再次显示完整内容",
  "key": {
    "id": 1,
    "key": "oc_live_4f8a2b1c9d3e7f6a5b8c1d2e3f4a5b6c",
    "prefix": "oc_live_4f8a2b1c",
    "name": "MyApp Production",
    "rate_limit": 60
  }
}

# 3. 调用生图
curl -X POST https://imageai.19k.xin/v1/images/generations \
  -H "Authorization: Bearer oc_live_4f8a2b1c9d3e7f6a5b8c1d2e3f4a5b6c" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"gpt-image-2",
    "prompt":"a cute cat",
    "size":"1024x1024",
    "n":1
  }'

# 响应(OpenAI 兼容)
{
  "created": 1781165211,
  "data": [{"url":"https://.../images/abc.png"}],
  "provider": "gptimage/gpt-image-2",
  "credits_charged": 8
}

图生图 — 输入参考图 + 提示词,生成新图。OpenAI /v1/images/edits 兼容,支持 multipart/form-data 和 JSON 两种方式。

参数	类型	必填	说明
prompt	string	✓	编辑指令,例如「把背景换成樱花」
image	string[]/file[]	✓	参考图数组,1-5 张。data:image/... 或 https://...
model	string		默认走 admin 配置的 image engine
size	string		默认 1024x1024
n	integer		1-4

# multipart 方式(macOS/Linux)
curl -X POST https://imageai.19k.xin/v1/images/edits \
  -H "Authorization: Bearer oc_live_xxx" \
  -F "image=@/path/to/cat.jpg" \
  -F "prompt=add a small flower on this cat" \
  -F "size=1024x1024" \
  -F "n=1"

# JSON 方式(推荐,可传远程 URL)
curl -X POST https://imageai.19k.xin/v1/images/edits \
  -H "Authorization: Bearer oc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt":"把头发染成酒红色",
    "image":["https://example.com/face.jpg"],
    "size":"1024x1536"
  }'

列出当前 OneCamera 配置的所有可用模型(火山 / GPT / Grok / DALL·E 等)。

查询当前 key 的用量统计(总请求数、生成图片数、剩余积分、限流等)。

查看当前 key 的元信息和所有者用户信息。

3.5 异步模式(可选)

GPT Image 2 等模型单张生成需 30-60 秒。默认 /v1/images/generations 是同步的(直接返图,OpenAI SDK 可直接用),但如果你不想长连接等待,可在请求体加 "async": true,接口会立即返回 task_id(HTTP 202),再轮询任务状态获取结果。

轮询任务状态。返回 status 为 queued / running / success / failed;成功时附带 data:[{url}]。任务失败会自动退回积分。

# 1. 提交异步任务,秒回 task_id
curl -X POST https://imageai.19k.xin/v1/images/generations \
  -H "Authorization: Bearer oc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"a cute cat","async":true}'

# 响应 202
{ "ok":true, "async":true, "task_id":"oc_task_ef4cdbbff6b0...", "status":"queued" }

# 2. 轮询(每 2-3 秒一次)
curl https://imageai.19k.xin/v1/images/tasks/oc_task_ef4cdbbff6b0... \
  -H "Authorization: Bearer oc_live_xxx"

# 完成时
{ "ok":true, "status":"success", "data":[{"url":"https://.../abc.png"}], "credits_charged":8 }

4. 限流

每个 key 默认每分钟 60 次请求,在 X-RateLimit-* 响应头中返回当前状态:

头	含义
X-RateLimit-Limit	每分钟上限
X-RateLimit-Remaining	本分钟剩余可用次数
X-RateLimit-Reset	下个窗口的 epoch 秒

超过限流时返回 HTTP 429 RATE_LIMITED。

5. 错误码

HTTP	error code	说明
400	EMPTY_PROMPT	prompt 为空
400	NO_IMAGE	edits 端点没传参考图
400	INVALID_JSON	请求体不是合法 JSON
401	UNAUTHENTICATED	缺少或无效的 API Key
402	INSUFFICIENT_CREDITS	积分不足,需充值
429	RATE_LIMITED	超过每分钟限流
500	GENERATION_FAILED	上游模型调用失败(积分会自动退回)
503	NO_ENGINE	管理员未配置任何图像引擎

6. 快速集成示例

Python

# pip install requests
import requests

API_KEY = "oc_live_4f8a2b1c9d3e7f6a5b8c1d2e3f4a5b6c"
BASE = "https://imageai.19k.xin"

# 1. 文生图
r = requests.post(
    f"{BASE}/v1/images/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"model": "gpt-image-2", "prompt": "a cute cat", "size": "1024x1024"},
)
print(r.json())

# 2. 图生图(传远程 URL)
r = requests.post(
    f"{BASE}/v1/images/edits",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "prompt": "turn her into cyberpunk style with neon lights",
        "image": ["https://example.com/face.jpg"],
    },
)
print(r.json())

Node.js

// npm install node-fetch
const fetch = require("node-fetch");

const API_KEY = "oc_live_4f8a2b1c9d3e7f6a5b8c1d2e3f4a5b6c";
const BASE = "https://imageai.19k.xin";

// 1. 文生图
const r1 = await fetch(`${BASE}/v1/images/generations`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "gpt-image-2", prompt: "a cute cat", size: "1024x1024" }),
});
console.log(await r1.json());

// 2. 图生图(本地文件,multipart)
const FormData = require("form-data");
const fs = require("fs");
const form = new FormData();
form.append("image", fs.createReadStream("face.jpg"));
form.append("prompt", "add a sunset background");
const r2 = await fetch(`${BASE}/v1/images/edits`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${API_KEY}`, ...form.getHeaders() },
  body: form,
});
console.log(await r2.json());

OpenAI 官方 SDK 兼容

由于本接口协议完全兼容 OpenAI image API,你也可以直接用 openai SDK:

# Python
from openai import OpenAI

client = OpenAI(
    api_key="oc_live_4f8a2b1c9d3e7f6a5b8c1d2e3f4a5b6c",
    base_url="https://imageai.19k.xin/v1",
)
resp = client.images.generate(
    model="gpt-image-2",
    prompt="a cute cat",
    size="1024x1024",
)
print(resp.data[0].url)

7. SDK 与社区

OneCamera 提供 OpenAI 兼容的 /v1 端点,因此市面上绝大多数 AI 图像 SDK (LangChain / LlamaIndex / Dify / Coze / 各种 AI Agent 框架) 都可以把 base_url 指向 https://imageai.19k.xin/v1 即可使用,模型选择 gpt-image-2 / dall-e-3 等。