渠道二 API 对接文档

鉴权与地址

API 调用使用客户 API Key，不使用网站账号密码。两个渠道共用同一把客户密钥与接口地址。JSON 请求使用 UTF-8 编码。

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请把密钥放在自己服务端的环境变量中，不写进公开网页、仓库或日志。目前公布地址使用 HTTP；通过公网传输密钥前请确认网络环境与站点安全地址。

curl 'http://gpt.laoma.667734.xyz/v1/models' \
  -H "Authorization: Bearer $IMAGE_API_KEY"

模型查询返回 {"object":"list","data":[{"id":"渠道二-seedream-5","object":"model","owned_by":"gateway"}]}。实际可调用组合还需要在价格公示中启用。

渠道、模型与计费

通过 model 的中文前缀选择渠道：渠道一- 或 渠道二-。没有单独的 channel 参数；同名模型的两个渠道是不同模型编号，不会自动跨渠道切换。

单张价格以 实时价格公示为准。文档不另存一套固定价格；未启用的模型与清晰度组合可能返回 price_not_configured。模型表是对接参数范围，不代表所有组合始终开放。

low、standard、hd 分别对应界面中的 1K、2K、4K 服务档位。size 主要选择比例，不是精确像素承诺；实际尺寸以下载图片为准，尤其渠道二不能仅凭 hd 推断一定是 4K 像素。

提交时通常预占“当前单张价格 × n”；任务成功后结算，失败、取消或执行超时释放预占。特殊账号的结算以其实际规则和账单为准。

接口列表

应优先使用返回的图片 URL，不自行拼接文件名。图片地址本身可用于访问图片，请勿公开分享私密作品的地址。

请求参数

推荐请求头：Idempotency-Key（最多200字符）与 X-Request-ID（最多128字符，仅允许字母、数字、点、下划线、冒号、连字符）。

异步提交与查询

curl 'http://gpt.laoma.667734.xyz/v1/images/generations/async' \
  -H "Authorization: Bearer $IMAGE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: image-order-20261005-001' \
  -H 'X-Request-ID: image-order-20261005-001' \
  --data-raw '{
    "model": "渠道二-seedream-5",
    "prompt": "一只戴着宇航员头盔的猫",
    "n": 1,
    "quality": "standard",
    "size": "16:9",
    "response_format": "url"
  }'

首次接收成功返回 HTTP 200，例如：

{
  "task_id": "img_example",
  "status": "queued"
}

queued 仅代表已接收，不代表生成成功。重复提交同一幂等任务时也可能直接返回 running、success 或 failed。

curl 'http://gpt.laoma.667734.xyz/v1/images/tasks/img_example' \
  -H "Authorization: Bearer $IMAGE_API_KEY"

轮询接口即使任务失败也可能返回 HTTP 200，必须判断 status。elapsed_ms 单位为毫秒；时间字段采用带时区的 ISO 8601，部分字段在排队期间为 null。

{
  "task_id": "img_example",
  "status": "success",
  "created_at": "2026-10-05T00:00:00.000+00:00",
  "started_at": "2026-10-05T00:00:01.000+00:00",
  "completed_at": "2026-10-05T00:01:01.000+00:00",
  "elapsed_ms": 60000,
  "data": [{
    "url": "http://gpt.laoma.667734.xyz/v1/images/files/example.png",
    "revised_prompt": "一只戴着宇航员头盔的猫"
  }]
}

上面是结构示例，不是真实可下载的文件。选择 b64_json 时，data 中图片字段改为 b64_json，请解码后自行保存。

参考图

两个渠道使用相同的 reference_images 参数。当前渠道二六个模型的接收链路都允许参考图，但接收请求不等于已验证每个模型的生成效果。需要保留角色或构图时，先以单图任务确认效果。渠道一参考图请优先使用 standard；部分 low 档位目前不传递参考图，不能用于保证参考一致性的任务。

支持 data URI 字符串，或包含纯 base64 与 MIME 的对象。不要传磁盘路径、普通 HTTP 图片地址、multipart 表单或伪造 size。size 字段并非必填，服务端会计算实际大小。

{
  "model": "渠道二-seedream-5",
  "prompt": "参考图片里的角色，生成正面全身设定图",
  "n": 1,
  "quality": "standard",
  "size": "2:3",
  "reference_images": [
    {"data": "BASE64_IMAGE_DATA", "mime_type": "image/png"}
  ]
}

BASE64_IMAGE_DATA 必须替换为真实图片的完整 base64。等价字符串写法为 "data:image/png;base64,完整图片数据"。JPEG 使用 image/jpeg，WebP 使用 image/webp；类型必须与图片内容一致。

多张参考图仍放在同一数组内，顺序保持一致。多图参考效果未作全面验收，不能把上传成功当成全部参考图都已生效；首次对接建议单张参考图。

参考图的体积限制按解码后的原始文件计算，base64 与 JSON 会增加请求体大小。超限、损坏、类型不符会被拒绝；大型请求也可能先被网站网关拒绝。

幂等重试与任务找回

为每一条独立业务任务生成一个唯一的 Idempotency-Key。网络断开或提交响应丢失时，用同一密钥、同一客户 API Key 与完全相同的请求参数重试，避免重复创建任务。修改提示词、模型、比例或参考图时应使用新的幂等键，否则返回409。

同一幂等键对应的失败任务通常仍返回该任务的失败结果，不会自动重跑；明确重新生成时换新幂等键。未接收的429拒单在额度或容量恢复后可重试。

提交前保存自己的 X-Request-ID。丢失 task_id 时按该编号查询：

curl 'http://gpt.laoma.667734.xyz/v1/images/tasks/by-request/image-order-20261005-001' \
  -H "Authorization: Bearer $IMAGE_API_KEY"

X-Request-ID 本身不提供幂等保证；每条任务应使用不同编号。响应头的 X-Request-ID 是服务器追踪号，请另行保存用于排障，不要与自己提交的找回编号混淆。

同步调用改用 POST /v1/images/generations，请求体相同，成功返回 {"created":1791158400,"data":[...]}，不含 task_id。客户端连接超时不代表已停止扣费，也不应立即创建重复任务；先找回或用同一幂等键查询/重试。同步等待受服务器预算限制，不承诺无限等待或三分钟必完成。

Python 完整调用示例

使用 Python 标准库，无需安装 SDK。环境变量 IMAGE_API_KEY 填客户密钥；IMAGE_API_BASE 可覆盖网站根地址。

import base64
import json
import os
import time
import uuid
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen

BASE = os.getenv("IMAGE_API_BASE", "http://gpt.laoma.667734.xyz").rstrip("/")
KEY = os.environ["IMAGE_API_KEY"]

def call(method, path, data=None, headers=None):
    body = None if data is None else json.dumps(data, ensure_ascii=False).encode("utf-8")
    request = Request(BASE + path, data=body, method=method, headers={
        "Authorization": "Bearer " + KEY,
        "Content-Type": "application/json",
        **(headers or {}),
    })
    try:
        with urlopen(request, timeout=60) as response:
            return json.load(response)
    except HTTPError as error:
        detail = error.read().decode("utf-8", "replace")
        raise RuntimeError(f"HTTP {error.code}: {detail}") from error

payload = {
    "model": "渠道二-seedream-5", "prompt": "一只戴着宇航员头盔的猫",
    "n": 1, "quality": "standard", "size": "16:9", "response_format": "url",
}
# 如需参考图，取消下一行注释；使用真实 PNG 文件。
# payload["reference_images"] = [{"data": base64.b64encode(Path("reference.png").read_bytes()).decode("ascii"), "mime_type": "image/png"}]
request_id = uuid.uuid4().hex
headers = {"Idempotency-Key": request_id, "X-Request-ID": request_id}
try:
    task = call("POST", "/v1/images/generations/async", payload, headers)
except (URLError, TimeoutError):
    # 使用同一幂等键和原请求体，仅重试一次，避免重复任务。
    task = call("POST", "/v1/images/generations/async", payload, headers)

task_id = task["task_id"]
print("任务编号：", task_id, "找回编号：", request_id, flush=True)
deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = call("GET", "/v1/images/tasks/" + task_id)
    if result["status"] == "failed":
        raise RuntimeError(f'{result.get("error_code")}: {result.get("error")}')
    if result["status"] == "success":
        for index, item in enumerate(result.get("data", []), 1):
            if "b64_json" in item:
                raw = base64.b64decode(item["b64_json"])
            else:
                with urlopen(item["url"], timeout=120) as image:
                    raw = image.read()
            # 使用 .bin 避免仅凭 URL 扩展名误判实际图片格式。
            Path(f"{task_id}_{index}.bin").write_bytes(raw)
        print("图片已保存")
        break
    time.sleep(3)
else:
    raise TimeoutError("客户端停止等待，请保留任务编号继续查询；不要盲目重复提交")

例子中的1800秒是客户端停止轮询的预算，不改变服务器任务上限。发生读取网络异常时保留已打印的任务编号，恢复后继续查询即可。

JavaScript 异步示例

适用于支持 fetch 的服务端环境。不要将真实 API Key 放进公开网页；提交前保存 requestId，网络异常时先找回任务或用原幂等键重试。

const base = "http://gpt.laoma.667734.xyz";
const key = process.env.IMAGE_API_KEY;
if (!key) throw new Error("缺少 IMAGE_API_KEY");
const requestId = crypto.randomUUID();
async function call(path, options = {}) {
  const response = await fetch(base + path, {
    ...options,
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
      ...(options.headers || {}),
    },
    signal: AbortSignal.timeout(60000),
  });
  const text = await response.text();
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${text}`);
  return JSON.parse(text);
}
const task = await call("/v1/images/generations/async", {
  method: "POST",
  headers: { "Idempotency-Key": requestId, "X-Request-ID": requestId },
  body: JSON.stringify({
    model: "渠道二-seedream-5", prompt: "一只戴着宇航员头盔的猫",
    n: 1, quality: "standard", size: "16:9", response_format: "url",
  }),
});
console.log("任务编号：", task.task_id, "找回编号：", requestId);
const deadline = Date.now() + 1800000;
for (;;) {
  const result = await call(`/v1/images/tasks/${task.task_id}`);
  if (result.status === "success") { console.log(result.data); break; }
  if (result.status === "failed") throw new Error(`${result.error_code}: ${result.error}`);
  if (Date.now() >= deadline) throw new Error("停止等待，请保留任务编号继续查询");
  await new Promise(resolve => setTimeout(resolve, 3000));
}

单图下载与 ZIP 归档

成功后尽快下载。图片可能按保留策略清理，返回 URL 不代表永久保存。下载文件的格式应依据响应 Content-Type 或图片内容判断，不只依据 URL 后缀。

curl -L '实际返回的图片URL' -o image.bin

curl 'http://gpt.laoma.667734.xyz/api/me/images/archive?limit=200' \
  -H "Authorization: Bearer $IMAGE_API_KEY" -o images.zip

curl 'http://gpt.laoma.667734.xyz/api/me/images/archive?task_id=img_example&limit=500' \
  -H "Authorization: Bearer $IMAGE_API_KEY" -o task-images.zip

归档默认最多200张，limit 最多500张，超过范围会被收敛到有效值。仅打包当前客户成功任务中仍存在的 URL 图片；可用 task_id 限定单个成功任务。没有可下载图片时返回404与 archive_empty。

此接口不是无限量全历史下载，也没有归档分页；只返回 base64 的结果不会从历史记录自动打包。成功响应类型为 application/zip，失败时为JSON，请先检查HTTP状态再保存归档。

在线充值

充值接口不在 /v1 下，使用网站根地址 http://gpt.laoma.667734.xyz。与图像接口一样使用客户 API Key 鉴权，不使用账号密码。积分按后台配置的 points_per_yuan 兑换（当前 1 元 = 100 积分），实际档位与单价以 /api/recharge/overview 返回的配置为准。

充值走的是上游码支付（易支付兼容协议），服务端已完成签名与异步通知校验：只有到账通知经服务端核验通过才会加积分，重复通知不会重复入账。客户端拿到的只是收款码与跳转地址。

读取充值配置

curl 'http://gpt.laoma.667734.xyz/api/recharge/overview' \
  -H "Authorization: Bearer $IMAGE_API_KEY"

返回可用支付方式、起充金额、快捷档位、订单有效期及该账号当前余额；不含任何密钥。

创建充值订单

curl -X POST 'http://gpt.laoma.667734.xyz/api/recharge/orders' \
  -H "Authorization: Bearer $IMAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 30, "pay_type": "alipay", "device": "pc"}'

成功返回订单对象，其中 status 为 pending。本版本使用页面支付，客户端应访问 submit_url，由本站生成签名表单并跳转到 502 码支付收银台。

{
  "ok": true,
  "order": {
    "out_trade_no": "RC20261010A1B2C3",
    "amount_yuan": 30.0,
    "points": 3000.0,
    "pay_type": "alipay",
    "status": "pending",
    "credited": false,
    "qrcode": "",
    "payurl": "",
    "urlscheme": "",
    "submit_url": "/api/recharge/orders/RC20261010A1B2C3/pay",
    "created_at": "...",
    "expires_at": "..."
  }
}

跳转收银台

直接访问 submit_url，本站会以 POST 表单跳转到 https://pay.502k.cn/xpay/epay/submit.php。不要再调用旧的二维码下单接口。

curl 'http://gpt.laoma.667734.xyz/api/recharge/orders/RC20261010A1B2C3/pay' \
  -H "Authorization: Bearer $IMAGE_API_KEY"

该地址需要当前客户登录或携带客户 API 密钥，返回已签名的收银台自动提交表单。订单为 pending 时可继续支付，其他状态返回 recharge_order_not_pending。

查询订单与到账状态

curl 'http://gpt.laoma.667734.xyz/api/recharge/orders/RC20261010A1B2C3' \
  -H "Authorization: Bearer $IMAGE_API_KEY"

# 顺带向上游核对一次（未支付时保持 pending）
curl 'http://gpt.laoma.667734.xyz/api/recharge/orders/RC20261010A1B2C3?sync=1' \
  -H "Authorization: Bearer $IMAGE_API_KEY"

到账后 status 变为 paid，credited 变为 true，并给出 paid_at / credited_at。积分以 credited=true 为准，不要只看 paid。查询只允许访问本账号订单，越权返回 recharge_order_not_found。

订单列表

curl 'http://gpt.laoma.667734.xyz/api/recharge/orders?limit=50' \
  -H "Authorization: Bearer $IMAGE_API_KEY"

按创建时间倒序返回本账号的充值记录，status 取值为 pending、paid、expired、failed。未支付且超过订单有效期的订单会被标记为 expired，需重新下单。

充值相关错误：recharge_disabled（在线充值未开放）、recharge_order_not_found（订单不存在或不属于当前账号）、recharge_order_not_pending（订单当前不可支付）、recharge_amount_too_small / recharge_amount_too_large（金额超出配置区间）、recharge_amount_mismatch（上游通知金额与订单不一致，订单转为 failed）。

错误响应与处理

提交或查询接口被拒绝时，HTTP状态为4xx/5xx，格式如下；task_id 查询本身成功但任务失败时，使用上文的 status=failed 结构。

{
  "error": {
    "message": "客户额度不足，请联系管理员充值",
    "type": "rate_limit_error",
    "code": "client_quota_insufficient",
    "param": null
  },
  "request_id": "服务器追踪号"
}

错误码列表不是穷举。网关还可能返回非JSON的413、502或504；先判断HTTP状态及Content-Type，再解析内容。对429或5xx采用有上限的退避，不要高频创建新任务。