客户接入文档

5分钟快速接入

1. 在登录页用邮箱验证码登录；首次验证自动创建三宝API独立账号。
2. 在钱包用支付宝固定套餐充值，币种为人民币（CNY）。
3. 在API Key页面创建 Key，并只保存在客户服务端。
4. 调用 GET /v1/models，从当前 Key 返回的 data[].id 选择公开模型。
5. 根据模型类型选择端点：视频调用 POST /v1/videos 并轮询 GET /v1/videos/{task_id}；GPT Image 2 图片调用 POST /v1/images/tasks 并轮询 GET /v1/images/tasks/{task_id}。保存创建响应的 id，不要把图片模型发往视频端点。下方快速示例仅演示视频，GPT Image 2 请看图片任务说明；Image 2.5 请看同步图片说明。

export SANBAO_API_KEY="sk-<YOUR_KEY>"
export SANBAO_PUBLIC_MODEL="从 GET /v1/models 返回的 data[].id 中选择"
curl -sS https://api.sanbaobeauty.com/v1/videos \
  -H "Authorization: Bearer $SANBAO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-20260802-0001" \
  -d "{\"model\":\"$SANBAO_PUBLIC_MODEL\",\"prompt\":\"海边日落，镜头缓慢推进\",\"duration\":5,\"resolution\":\"720p\",\"ratio\":\"16:9\",\"images\":[]}"

成功码：视频创建响应以实际返回为准；图片异步创建返回 HTTP 202 Accepted。客户端必须接受任意 2xx；同一幂等键的安全重放可能返回 200 OK。

账号、充值与 API Key

三宝API账号、余额、Key和任务与主站相互独立。邮箱验证码登录是公开入口，首次验证会自动创建独立账号；已登录用户可用支付宝固定套餐充值。

Authorization: Bearer sk-<YOUR_KEY>

建议按应用和环境拆分Key并设置模型范围、额度和有效期。不要把登录Cookie当作API Key，也不要把Key放入查询串、网页、App或公开仓库。使用前请阅读用户协议、隐私政策、充值与退款规则及内容合规及禁止用途。

查模型、公开调用 ID 与计费

curl -sS https://api.sanbaobeauty.com/v1/models \
  -H "Authorization: Bearer $SANBAO_API_KEY"

model 只能使用认证响应的 data[].id，不要使用中文展示名，也不要猜测或缓存已经下架的ID。

只调用实时目录中当前Key可见的模型。价格、调用ID、时长、比例、分辨率和素材上限以模型广场及 GET /v1/models 为准；不要硬编码模型数量或旧能力。

创建异步视频任务

POST /v1/videos，JSON请求。当前没有面向API客户的独立文件上传端点；素材使用服务端可直接读取的HTTPS URL。

素材 URL

• 必须为公网 https://；不能是blob/data、localhost、内网地址、需Cookie/Referer的页面或登录后链接。
• 有效期须覆盖排队和生成并预留至少1小时；URL应直接返回文件，避免HTML下载页和多次跳转。
• 无Cookie GET应成功并返回合理的Content-Type/Content-Length；数量、格式和大小须符合实时能力。
• 不要在URL中放API Key、个人信息或永久凭据。

幂等

发送 Idempotency-Key（1–128字符），每个业务订单固定一个随机值。网络超时后用相同Key和完全相同请求体重试；不要换Key盲目重提。相同Key配不同请求会被拒绝。按秒模型强制要求，按次模型也建议始终发送。

创建响应

HTTP/1.1 201 Created
Content-Type: application/json

{"id":"video_example_01","object":"video","model":"example-public-id","status":"queued","created_at":1785571200}

客户端应接受任意2xx、忽略未知字段且不依赖字段顺序。

查询状态与下载

curl -sS https://api.sanbaobeauty.com/v1/videos/video_example_01 \
  -H "Authorization: Bearer $SANBAO_API_KEY"

queued

已接收或排队。

processing / in_progress

生成或成品文件处理中。

succeeded / completed

成功，读取成品链接。

failed

失败终态。

canceled

取消终态；客户取消接口暂未开放，但客户端应能识别。

建议首次等2秒，再按2、3、5、8、10秒放慢，稳定后每10–15秒轮询并加10%–30%抖动。本地超时只停止轮询，不代表任务失败，不能自动新建任务。

{"id":"video_example_01","object":"video","status":"succeeded","video_url":"https://example.invalid/signed-result.mp4","download_url":"https://example.invalid/signed-download.mp4","link_expires_in":86400}

成品链接是短期签名URL。过期或接近过期时，用同一Key重新查询同一任务刷新；不要当永久地址缓存。对象存储CORS可能阻止浏览器读取，三宝API不保证任意网页Origin可直连。

服务端流式转存

客户服务端GET download_url（缺失时用 video_url），以背压流式写入自己的对象存储，不整段读入内存或落盘。校验Content-Length、实际字节数、目标HEAD长度并计算SHA-256。源链接401/403时先重新查询任务刷新链接，不要重试旧签名。

Node.js / Python 最小示例

Node.js 18+

const base = 'https://api.sanbaobeauty.com/v1';
const headers = {Authorization:`Bearer ${process.env.SANBAO_API_KEY}`};
const models = await fetch(`${base}/models`, {headers}).then(r => r.json());
const model = process.env.SANBAO_PUBLIC_MODEL; // 从模型广场选择视频ID，并按能力调整下方参数
if (!models.data.some(item => item.id === model)) throw new Error("请设置当前可见的视频模型ID");
const response = await fetch(`${base}/videos`, {method:'POST', headers:{...headers,'Content-Type':'application/json','Idempotency-Key':crypto.randomUUID()}, body:JSON.stringify({model,prompt:'海边日落，镜头缓慢推进',duration:5,resolution:'720p',ratio:'16:9',images:[]})});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
console.log((await response.json()).id);

Python 3.10+

import os, uuid, requests
base = "https://api.sanbaobeauty.com/v1"
headers = {"Authorization":f"Bearer {os.environ['SANBAO_API_KEY']}"}
model = os.environ["SANBAO_PUBLIC_MODEL"]  # 选择视频ID，并按能力调整下方参数
models = requests.get(f"{base}/models", timeout=30, headers=headers).json()["data"]
assert any(item["id"] == model for item in models), "模型ID当前不可见"
r = requests.post(f"{base}/videos", timeout=(10,60), headers={**headers,"Idempotency-Key":str(uuid.uuid4())}, json={"model":model,"prompt":"海边日落，镜头缓慢推进","duration":5,"resolution":"720p","ratio":"16:9","images":[]})
r.raise_for_status()
print(r.json()["id"])

错误、退款与退避

{"code":"invalid_video_parameters","message":"duration 不在模型支持范围内"}

失败退款：任务明确failed/canceled时，预留费用按运行时账务规则幂等退回；成功只结算一次。创建结果不确定会先隔离对账，不盲目重提或提前重复退款。

安全与浏览器边界

• Key只放客户服务端环境变量或密钥系统；本文Key、任务ID和URL均为假值。
• 日志、错误回包、埋点、前端源码和聊天不记录Key或签名URL。
• 三宝API未为任意浏览器Origin开放带凭据的通用CORS。浏览器不要直带长期Key；由客户服务端代理并做鉴权、限流和审计。
• 验证素材/成品重定向仍为HTTPS和预期主机，禁止把敏感头转发到其他域名。
• 设置连接/读取超时、最大文件、并发、背压和完整性校验；Multipart失败要Abort，不确定先HEAD再重试。

视频与图片任务接口

Base URL：https://api.sanbaobeauty.com/v1。以模型广场中的公开模型 ID 和当前人民币价格为准；不同分辨率使用各自的模型 ID。所有创建、查询与结果下载均需要 API Key。

视频任务

创建使用 POST /v1/videos，查询使用 GET /v1/videos/{id}，下载使用 GET /v1/videos/{id}/content。使用 model、prompt、duration、ratio 和该模型支持的参考素材字段；时长、比例、素材数量以模型广场能力说明为准。

单分辨率模型可省略 resolution；显式传入时必须与该公开模型 ID 的分辨率一致。按秒任务必须提供 Idempotency-Key。按次任务建议同样提供：同一请求重试时保留原键和原内容。旧按次客户端省略该键仍可提交，但每次请求独立计费，不能跨请求去重。

图片任务（异步、按次计费）

gpt-image2、gpt-image2-1K、gpt-image2-2K、gpt-image2-4K 使用 POST /v1/images/tasks，不使用同步的 /v1/images/generations。每次新任务设置新的 Idempotency-Key，同一请求重试时保留原键及原请求内容。

curl https://api.sanbaobeauty.com/v1/images/tasks \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: image-example-0001' \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-image2-2K","prompt":"清晨窗边的一只橘猫","aspect_ratio":"9:16","images":[]}'

创建返回 HTTP 202 和任务 id。随后使用 GET /v1/images/tasks/{id} 查询；完成后返回的 image_url 指向 /v1/images/tasks/{id}/content。图片读取接口支持 GET、HEAD 和 Range，需要同一用户和创建任务的 Key。

图片状态包括 queued、in_progress、completed、failed 和 submission_unconfirmed。提交结果暂未确认时保留原任务与预留金额，请继续查询该 ID，不要换新键重复提交。确认失败后退回预留金额。

最多 5 张 HTTPS 参考图片，不接受视频或音频。基础版默认比例 auto，1K 默认 auto 且支持 9:21；2K 和 4K 默认 9:16，不支持 auto。完整比例清单见各模型能力说明。

计费与结果

每次任务提交时冻结适用价格及账户倍率：按次任务按 1 次计算，按秒任务按允许的生成时长计算。异步处理中不要以刷新页面、网络超时或未知状态直接判定失败。已确认失败的任务只退款一次；重复查询不会重复扣费或退款。请保存任务 ID，并在任务完成后通过本站鉴权下载接口获取结果。

Image 2.5 同步图片生成

image_2_5_flare（Image 2.5 Flare）和 image_2_5_sunburst（Image 2.5 Sunburst）使用 POST /v1/images/generations，每次 ¥0.07，成功响应直接返回一张图片。支持七种常用画幅、1K 输出和最多 9 张参考图，JPEG/PNG。

curl https://api.sanbaobeauty.com/v1/images/generations \
  -H "Authorization: Bearer $SANBAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"image_2_5_flare","prompt":"清晨窗边的一只橘猫","aspect_ratio":"16:9","resolution":"1K","n":1,"output_format":"jpeg","response_format":"url","images":[]}'

成功结果位于 data[0].url 或 data[0].b64_json。失败不收费；网关不会自动重放生成请求。超时或断开连接时，供应商可能仍在处理，请勿自动重试；客户端再次提交会创建新的独立请求。

版本与变更

• 2026-09-09：按前端启用目录拆分分辨率，新增视频直连合同和4款原生异步图片；补齐缺省分辨率、持久幂等、冻结计费及本站鉴权媒体读取。实际可调用项以当前Key目录为准。
• 2026-08-08：统一邮箱验证码直接登录、视频模型正式白名单和法务规则入口；图片模型继续不开放。
• 2026-08-02：文档按实时认证模型目录呈现按次/按秒能力，示例不固化模型数量、临时任务ID或可能下架的调用ID。
• 2026-08-01：补齐登录、充值、Key、创建、轮询、下载、201/2xx、幂等、退款、退避、CORS与签名刷新。

客户端应接受所有2xx、忽略未知字段，并以实时目录为能力和价格依据；没有出现在认证目录中的灰度模型不可调用。