接口文档

OpenAI Images 风格的 AI 生图接口。支持同步出图与异步批量任务两种模式。

基本信息

Base URL	`…`/v1
认证	请求头 `Authorization: Bearer sk-tra-xxx`（API Key 由平台方发放）
响应格式	JSON。出错时返回 `{ "error": { "message", "type", "code" } }`
单号	每次出图返回全局唯一 `request_id`，是成功/失败/扣费/排查的唯一凭据，请记录它
图片托管	返回的图片 URL 由平台托管 30 天，请及时下载保存到自己的存储
客户端超时	同步接口建议 ≥600 秒，4K 更久；对超时敏感请用异步任务接口

接口列表

方法	路径	说明
GET	`/v1/models`	可用模型列表
POST	`/v1/images/generations`	文生图，JSON，同步返回图片 URL
POST	`/v1/images/edits`	图生图/图片编辑，multipart 上传参考图（最多 4 张，每张 ≤10MB），同步返回
POST	`/v1/tasks`	异步批量文生图（≤10 个 prompt），立即返回单号，后台生成
GET	`/v1/tasks/{request_id}`	按单号查询任务状态与结果
GET	`/v1/credits`	查询当前 Key 的积分余额

文生图（同步）

curl "…/v1/images/generations" \
  -H "Authorization: Bearer sk-tra-xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260824-001" \
  -d '{
    "model": "tra-image-1",
    "prompt": "一只橘猫坐在干净的产品摄影台上",
    "size": "1024x1024",
    "quality": "standard"
  }'

参数

字段	必填	说明
model	是	目前为 `tra-image-1`，完整列表见 `GET /v1/models`
prompt	是	图片描述，建议写清主体、场景、风格、光线、构图
size	否	`宽x高`，默认 `1024x1024`，推荐值见下表；不支持 `auto`
quality	否	`standard`/`1k`（默认）、`hd`/`2k`、`4k`/`high`/`ultra`
n	否	固定单张输出，只能省略或传 `1`

响应

{
  "request_id": "5ef4f2c8-38c7-4087-b672-c208302bc43f",
  "created": 1756000000,
  "data": [{ "url": "…/files/xxxx.png" }],
  "credits_cost": 0.96,
  "status": "completed",
  "duration_ms": 70512
}

图生图（同步）

curl "…/v1/images/edits" \
  -H "Authorization: Bearer sk-tra-xxx" \
  -F "model=tra-image-1" \
  -F "prompt=保留主体产品不变，把背景改成浅灰摄影棚，柔和阴影" \
  -F "size=1024x1024" \
  -F "image=@reference.png"

参数同文生图，外加 image 文件字段（可重复传，最多 4 张参考图）。响应格式相同。

异步批量任务

一次提交多个 prompt（最多 10 个），立即返回单号列表，后台逐个生成。按个扣费：提交时每个 prompt 预扣一份积分，失败自动退还。

curl "…/v1/tasks" \
  -H "Authorization: Bearer sk-tra-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tra-image-1",
    "prompts": ["橘猫产品图", "柴犬产品图", "仓鼠产品图"],
    "size": "1024x1024"
  }'

响应（HTTP 202）：{ "object": "batch", "tasks": [{ "request_id": "…", "status": "pending" }, …], "credits_cost": 2.88 }。余额不足支付全部时，支付不起的任务直接标 failed 且不扣费。异步模式目前仅支持文生图。

任务查询与断连恢复

curl "…/v1/tasks/22c0ff37-dc59-4633-b5a1-00b70429947c" \
  -H "Authorization: Bearer sk-tra-xxx"

status	含义	积分
`pending`	排队中或生成中	已预扣
`completed`	成功，`data` 里有图片 URL	已扣除
`refunded`	生成失败，积分已退还	已退还
`failed`	未执行（余额不足等），未扣费	未扣
`upstream_charged`	上游已出图但平台转存失败，积分已退还	已退还

断连恢复：同步接口等待中如果客户端超时断开，不要直接重试——凭 request_id 调本接口查询：pending 继续等，completed 直接取结果。只能查自己 Key 名下的任务。

重试与幂等

同步接口支持请求头 Idempotency-Key: <你的唯一值>（如订单号+序号）。带相同键重复提交：直接返回原任务结果，不会重复扣费；原任务还在生成中则返回 409 idempotency_conflict。网络超时/5xx 时带同一幂等键重发或凭单号查询；4xx 不要重试。

限流规则

每 Key 默认 3 个并发、全站合计 20 个。超限返回 429 rate_limited，不扣费，请指数退避（5s/15s/45s）。批量需求请用异步任务接口，不要自己开大量并发。

Node.js 示例

const res = await fetch('…/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': `job-${jobId}`,
  },
  body: JSON.stringify({ model: 'tra-image-1', prompt: '一只橘猫', size: '1024x1024' }),
})
const body = await res.json()
if (!res.ok) throw new Error(`${body.error.message} (request_id: ${body.request_id})`)
console.log(body.data[0].url, body.request_id)

OpenAI SDK 接入

接口与 OpenAI Images API 同构，官方 SDK 把 base_url 指过来即可用（timeout 设 600 秒）。注意 SDK 会丢弃 request_id 等扩展字段，需要对账单号时请用原生 HTTP 或异步任务接口。

计费

按 quality 档位扣积分，提交时预扣，生成失败自动退还：

档位	quality 取值	积分
1K 标准	`standard` / `1k`（默认）	0.96
2K 高清	`hd` / `2k`	1.44
4K 高质量	`4k` / `high` / `ultra`	2.40

扣费与退款语义

场景	积分处理
参数校验失败（400）	不扣费
积分不足（402）	不扣费
限流（429）	不扣费
上游生成失败（502）	预扣后自动全额退还
客户端超时/断连	任务继续执行：成功正常扣费，失败自动退还；凭单号查结果
平台服务重启	在途任务一律自动退款，状态可查

余额精确到 0.001 积分，所有扣费/退款/充值均有流水，争议时凭 request_id 向平台方核查。

档位	尺寸
1K	1024x1024, 1280x720, 720x1280, 1536x1024, 1024x1536, 1152x864, 864x1152, 1456x624
2K	2048x2048, 2560x1440, 1440x2560, 2496x1664, 1664x2496, 2304x1728, 1728x2304
4K	3840x2160, 2160x3840, 2480x2480, 3328x1872, 2880x2160, 2784x2224

错误码

HTTP	code	说明
401	invalid_api_key	Key 无效、已禁用或已过期
400	invalid_request_error / bad_request	参数错误、请求体格式非法
402	insufficient_credits	积分不足，未扣费
404	not_found	资源不存在（含他人单号）
409	idempotency_conflict	相同幂等键的请求仍在生成中
413	request_too_large	上传超限（单文件 ≤10MB）
429	rate_limited	触发限流，退避重试
502	generation_failed	生成失败，积分已退还
500	internal_error	平台内部错误

注意事项

· 图片 URL 无需认证即可访问，注意不要泄露给不希望看到图片的人。
· 内容安全由生成引擎审核，违规 prompt 会生成失败并退还积分。
· 排查问题请提供 request_id，平台方可凭它查到完整链路（参数、扣费流水、错误、耗时）。
· Agent 对接：向平台方索取 tra-image-gen skill 文件，放入你的 agent skills 目录即可。

变更日志

· 2026-08-24 v2：响应新增 request_id；新增异步批量任务与单号查询；支持 Idempotency-Key 幂等重试；明确限流规则；补全扣费/退款语义；错误格式统一。同步接口保持向后兼容（仅新增字段）。
· 2026-08-24 v1：首版，同步文生图/图生图。