调用文档

Open API v1 · 鉴权、接口清单、错误码与示例。接口已上线，以下为真实契约（字段以线上返回为准）。

v1.0更新于 2026-10-30

鉴权

开放 API 使用 API Key 鉴权，放在请求头：

Authorization

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
X-Idempotency-Key: 3f1c9e2a-8b7d-4f1a-9c5e

Key 明文只在创建时展示一次，服务端仅保存哈希与前缀；列表只能看到前缀与后 4 位。
Key 吊销 / 账户禁用后立即失效（HTTP 401 / 信封 code=401）。
所有响应使用统一信封 { code, msg, data, requestId }；成功 code=200。
写接口支持 X-Idempotency-Key（8-64 位字母数字与 -_）；同键重放返回首次结果，不重复扣费。

接口清单

图片生成

POST /v1/images/generations

curl

curl -X POST "https://openapi.sczhiyun.net/v1/images/generations" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 3f1c9e2a-8b7d-4f1a-9c5e" \
  -d '{
    "model": "1",
    "prompt": "赛博朋克风格的夜市街头，霓虹灯牌倒映在雨后的积水里",
    "ratio": "1:1",
    "quality": "1K",
    "n": 1
  }'

JavaScript (fetch)

const res = await fetch('https://openapi.sczhiyun.net/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk-xxxxxxxx',
    'Content-Type': 'application/json',
    'X-Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    model: '1',
    prompt: '赛博朋克风格的夜市街头',
    ratio: '1:1',
    quality: '1K',
  }),
})
const { code, msg, data, requestId } = await res.json()
if (code !== 200) throw new Error(`[${code}] ${msg} (requestId: ${requestId})`)
console.log('task id:', data.id, 'balance:', data.balance)

Python (requests)

import requests, uuid

resp = requests.post(
    "https://openapi.sczhiyun.net/v1/images/generations",
    headers={
        "Authorization": "Bearer sk-xxxxxxxx",
        "Content-Type": "application/json",
        "X-Idempotency-Key": str(uuid.uuid4()),
    },
    json={"model": "1", "prompt": "赛博朋克风格的夜市街头", "ratio": "1:1", "quality": "1K"},
    timeout=30,
)
body = resp.json()
if body["code"] != 200:
    raise RuntimeError(f'{body["code"]} {body["msg"]} {body.get("requestId")}')
print(body["data"]["id"])

创建成功返回任务 id 与预扣金额 amount、扣后余额 balance；再用任务查询接口轮询结果。

响应示例（创建任务）

{
  "code": 200,
  "msg": "ok",
  "requestId": "req_01H...",
  "data": {
    "id": "AP20261029211945251009",
    "object": "image.generation",
    "model": "1",
    "status": "running",
    "quantity": 1,
    "amount": 0.1,
    "balance": 9.7,
    "created": 1793308785,
    "reused": false
  }
}

任务查询

GET /v1/tasks/{id}

status 枚举：

响应示例（成功）

{
  "code": 200,
  "msg": "ok",
  "requestId": "req_01H...",
  "data": {
    "id": "AP20261029211945251009",
    "task_no": "AP20261029211945251009",
    "object": "image.generation",
    "model": "1",
    "status": "succeeded",
    "progress": 100,
    "quantity": 1,
    "amount": 0.1,
    "asset_url": "https://upstream-cdn.example.com/xxx.png",
    "expires_hint": "2026-10-30T21:19:45Z",
    "created_at": "2026-10-29 21:19:45",
    "finished_at": "2026-10-29 21:19:45"
  }
}

成功时 asset_url 为上游资产链接，平台不下载、不转存；expires_hint 为过期提示。

失败时返回 failure_code 与 message，余额按规则退回：

模型列表

GET /v1/models

返回当前 API 可售模型与 SKU、计费单位、API 售价、限流；只含平台已开放且在架的 SKU。

响应示例

{
  "code": 200,
  "msg": "ok",
  "data": {
    "object": "list",
    "data": [
      {
        "id": "1",
        "object": "model",
        "owned_by": "mock",
        "name": "Mock 生图 1K · 1K",
        "sku_no": "MOCK-IMG-1K",
        "capability": "image",
        "unit": "张",
        "price": 0.1,
        "currency": "CNY",
        "qps": 10,
        "daily_limit": 1000,
        "available": true
      }
    ]
  }
}

错误码

限流与配额

按 Key / 账号两级 QPS 与日调用上限；超限返回 HTTP 429 + code=429。
模型级 QPS / 日限见模型广场与 GET /v1/models 的 qps/daily_limit 字段。
余额不足直接拒绝（不创建任务），返回 code=402。

结果链接声明

请务必阅读

返回的是上游资产链接（asset_url），有效期以供应商为准（通常 24 小时）；平台不保存文件、不承诺过期后可访问。请在有效期内下载并转存到自己的存储。

幂等、重试与退款

写接口支持 X-Idempotency-Key，同键重放返回首次结果，不重复扣费。
提交预扣余额；失败自动重试，最终失败按规则退款（流水类型 refund）。
失败码对 API 用户可见（不含上游敏感信息），便于排障。

鉴权