API 文档

OpenAI Images 兼容接口。用卡密作为密钥，通过 HTTP 或任意 OpenAI SDK 生成图片。 同步出图：一次 POST /images/generations 直接返回图片结果，与 OpenAI 完全一致。

鉴权生成图片图生图响应与图片链接拉取图片查询卡密使用记录错误码

使用规范 · 禁止生成非法内容

本服务仅供合法用途。严禁生成任何违法、违规或侵权内容，包括但不限于：

涉及未成年人的色情或性暗示内容（零容忍）
色情、血腥暴力、恐怖主义、极端仇恨内容
伪造证件、货币、公章，或用于诈骗的虚假图像
未经授权使用他人肖像、侵犯隐私或知识产权的内容
所在司法辖区法律法规禁止的其他内容

系统对每次请求进行内容审核并自动拦截违规请求；违规将累计警告、冻结或封禁卡密并记录审计，情节严重者依法移交相关部门处理。使用本服务即表示你已阅读并同意本规范。

鉴权与基础地址

Base URL：http://70.39.178.175:3037/api/v1

用卡密作为密钥。支持两种传法（任选其一）：Authorization: Bearer 你的卡密（OpenAI SDK 兼容）或 x-card-key: 你的卡密。

卡密即密钥，请妥善保管，不要在公开前端硬编码。当前为 HTTP，正式使用建议配置域名与 HTTPS。

生成图片

POST/images/generations

与 OpenAI /v1/images/generations 完全兼容。同步返回：请求会阻塞到出图完成，直接在响应里给出图片（默认返回 URL，也可 b64_json）。用任意 OpenAI SDK，把 base_url 指向本服务、api_key 填卡密即可。

请求体（JSON）参数：

参数	类型	必填	说明
prompt	string	必填	图片描述，最长 8000 字符
model	string	可选	模型名，缺省使用服务端默认模型
n	integer	可选	生成数量，默认 1（受供应商上限限制）；每张独立计费
size	string	可选	尺寸，默认 1024x1024。支持 1K(1024x1024 / 1024x1536 / 1536x1024)、2K(2048x2048)、4K(4096x4096)，清晰度越高扣费越多
image	string \| string[]	可选	图生图参考图（公网图片 URL / data URI / base64），传入即走图生图；最多 10 张，单张 ≤ 9MB。别名 images 亦可
quality	string	可选	auto / low / medium / high
background	string	可选	transparent（透明背景 PNG，适合 logo/贴纸/抠图素材，仅 1K 尺寸支持真透明；2K/4K 为超清放大图会返回不透明）/ opaque / auto
mask	string	可选	局部重绘蒙版（data URI / base64），仅图生图有效。透明区域为重绘区，其余尽量保持原样
response_format	string	可选	url（默认，返回带签名的临时图片链接）或 b64_json（内联 base64，单图 ≤ 32MB）
idempotency_key	string	可选	幂等键，相同键不重复扣费；10 分钟内重放会返回同一批图片

cURL 示例

bash

curl -X POST http://70.39.178.175:3037/api/v1/images/generations \
  -H "Authorization: Bearer 你的卡密" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只戴贝雷帽的柯基，柔和光线，胶片质感",
    "size": "1024x1024",
    "quality": "high"
  }'

OpenAI Python SDK

python

from openai import OpenAI

client = OpenAI(base_url="http://70.39.178.175:3037/api/v1", api_key="你的卡密")

resp = client.images.generate(
    prompt="一只戴贝雷帽的柯基，柔和光线，胶片质感",
    size="1024x1024",
)
print(resp.data[0].url)   # 带签名的临时图片链接，10 分钟内有效

分档计费

按分辨率分档扣点（1 元 = 100 点），总消耗 = 单张点数 × 数量(n)。默认档位如下（管理员可调整，实际以 /images/options 返回为准）：

· 1K（1024px）= 4 点/张 — 日常出图
· 2K（2048px）= 8 点/张 — 细节更丰富
· 4K（4096px）= 10 点/张 — 超清大图

各档位、价格与数量上限可通过 GET /images/options 实时获取（公开只读，无需鉴权），前端据此动态渲染。

图生图（参考图）

POST/images/generations带 image 字段即自动走图生图

在生成请求里加入 image 参考图，系统会以参考图为基础按 prompt 生成新图。支持三种格式：公网图片 URL（http/https）、data URI、裸 base64。最多 10 张参考图，单张 ≤ 9MB（png / jpeg / webp）。响应格式与文生图完全一致（同步返回 data[]）。若上游模型不支持图生图，会以明确错误提示失败。

bash

# 公网图片 URL（推荐，无需客户端做 base64 编码）
curl -X POST http://70.39.178.175:3037/api/v1/images/generations \
  -H "Authorization: Bearer 你的卡密" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "把这张照片改成动漫风格",
    "size": "1536x1024",
    "image": ["https://your-cdn.com/photo.png"]
  }'

bash

# data URI 形式（前端 FileReader / 移动端常见）
curl -X POST http://70.39.178.175:3037/api/v1/images/generations \
  -H "Authorization: Bearer 你的卡密" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "把这张照片改成水彩风格",
    "size": "1024x1024",
    "image": ["data:image/png;base64,iVBORw0KGgo..."]
  }'

计费与文生图一致，按 size 档位 × 数量扣点。参考图仅用于本次生成、不落库、不留存。公网 URL 会由服务端安全下载（SSRF 防护、体积限制、Content-Type 校验），仅允许指向公网的图片地址。

响应与图片链接

响应是标准 OpenAI 结构。data[] 的每一项按 response_format 返回 url 或 b64_json。额外多一个 task_id 字段（本服务扩展，用于事后在使用记录里定位这次出图）。

response_format=url（默认）

json

{
  "created": 1710000000,
  "task_id": "1tkCMaGXyhmDYnQm-7TyP",
  "data": [
    {
      "url": "http://70.39.178.175:3037/api/v1/files/1tkCMaGXyhmDYnQm-7TyP/0?exp=1786027761168&sig=Xa1...",
      "revised_prompt": "..."
    }
  ]
}

· url：带签名的临时图片链接，签名即授权，可直接 GET 或用在 <img src>，无需再带卡密。
· 链接留存 10 分钟，过期后返回 410（GONE）。请在 10 分钟内拉取保存。
· 单张图片最大 2GB，通过流式服务，适合超清大图。

response_format=b64_json

json

{
  "created": 1710000000,
  "task_id": "1tkCMaGXyhmDYnQm-7TyP",
  "data": [
    { "b64_json": "iVBORw0KGgoAAAANS...", "revised_prompt": "..." }
  ]
}

b64_json 会把整张图内联进 JSON，仅适合常规尺寸。单张超过 32MB 会拒绝内联并提示改用 url（大图请用默认 url 模式，走流式下载）。

拉取图片

GET/files/{task_id}/{index}

data[].url 就指向这个端点，且已带 ?exp=&sig= 签名——直接 GET 即可，无需鉴权头，浏览器 <img> 也能直接引用。签名与 10 分钟留存期绑定，过期返回 410。

bash

# 直接用响应里的签名 URL 保存
curl "http://70.39.178.175:3037/api/v1/files/1tkCMaGXyhmDYnQm-7TyP/0?exp=1786027761168&sig=Xa1..." -o out.png

完整示例：生成并保存（Python）

python

import requests

BASE = "http://70.39.178.175:3037/api/v1"
KEY = "你的卡密"

# 同步出图：一次请求直接拿到结果
r = requests.post(f"{BASE}/images/generations",
    headers={"x-card-key": KEY},
    json={"prompt": "一只戴贝雷帽的柯基，柔和光线", "size": "1024x1024"},
    timeout=180,
)
r.raise_for_status()
data = r.json()["data"]

# data[].url 自带签名，直接拉取保存（10 分钟内有效）
for i, item in enumerate(data):
    img = requests.get(item["url"], timeout=180)
    with open(f"out_{i}.png", "wb") as f:
        f.write(img.content)

图片留存 10 分钟，过期返回 410（GONE）。请及时拉取保存，服务端不长期留存。若响应中途断连，可用 task_id 在使用记录里重新拿到链接（仍在 10 分钟内）。

查询卡密

GET/card/me

返回卡密余额、状态、有效期与最近记录。

bash

curl http://70.39.178.175:3037/api/v1/card/me -H "x-card-key: 你的卡密"

使用记录

两种传法查任务记录。下游对接建议用 /external/* 这套：卡密放在请求体，无需额外 Header。

POST/external/tasks

分页列出该卡密的所有任务（不含原始描述文本）。可选 status 过滤：succeeded / failed / rejected。

bash

curl -X POST http://70.39.178.175:3037/api/v1/external/tasks \
  -H "Content-Type: application/json" \
  -d '{ "cardCode": "你的卡密", "page": 1, "pageSize": 20, "status": "succeeded" }'

POST/external/extract

查单个任务的详情与产出元数据（含 outputs[].url，10 分钟内可拉取）。用列表拿到的 taskId，或提交时用过的 idempotencyKey 定位。适合响应中途断连后重新取图。

bash

curl -X POST http://70.39.178.175:3037/api/v1/external/extract \
  -H "Content-Type: application/json" \
  -d '{ "cardCode": "你的卡密", "taskId": "1tkCMaGXyhmDYnQm-7TyP" }'

GET/tasks?page=1&pageSize=20

等价的 Header 鉴权版本（卡密放 x-card-key），适合已用 SDK 传卡密的场景。

bash

curl "http://70.39.178.175:3037/api/v1/tasks?page=1&pageSize=20" -H "x-card-key: 你的卡密"

错误码

HTTP	含义
400	请求参数错误（含 b64_json 图片超 32MB，请改用 url）
401	卡密缺失或无效 / 图片链接签名无效或已过期
402	卡密余额不足
403	内容违规被拦截 / 卡密被冻结或封禁
404	模型不可用 / 任务或图片不存在（或不属于该卡密）
409	幂等键此前已失败、未过审或仍在处理中
410	图片已过期（超过 10 分钟留存，已被清理）
429	请求过于频繁（单卡约 30 次/分钟）
502	上游生成失败（已自动退还额度）

错误响应格式

json

{ "error": { "message": "卡密余额不足", "type": "insufficient_balance", "code": "insufficient_balance" } }