帧间 API

使用帧间接口创建与查询任务，余额和售价与网页共用。

1. 地址与密钥

工作台 →「API 接入」创建密钥。创建时选择模型分类；选「全部模型」可调用当前全部可售模型。密钥只在创建时显示一次，最多保留 10 把有效密钥。

Base URL：正在读取

Authorization: Bearer fk-…

2. 推荐调用顺序

1. GET /models 取可用模型与 id（提交时只用这里的 id）
2. 需要参考素材时 POST /assets 上传，拿到素材 id
3. POST /videos 或 POST /images/generations 提交任务（必须带 Idempotency-Key）
4. GET /tasks/{id} 轮询，直到 completed / failed
5. 下载 /tasks/{id}/video 或 /tasks/{id}/image/0

3. 查询模型与余额

BASE="__BASE__"
KEY="fk-你的密钥"

curl "$BASE/models" -H "Authorization: Bearer $KEY"
curl "$BASE/balance" -H "Authorization: Bearer $KEY"

金额单位见各模型的 price_unit：视频和图片为人民币分（CNY_cent，如 20 = ¥0.20）；大模型输入、输出和缓存为人民币元/百万 Token（CNY_per_million_tokens）。

视频按模型标明的单位计费：second 为每秒售价 × 所选秒数，request 为每条固定总价。rates 是对应清晰度、时长的整条总价。视频超分按原片实际时长向上取整到秒。

模型、介绍和当前售价以模型列表为准。

可回传模型列表的 pricingFingerprint 为 pricing_fingerprint，或使用 X-Pricing-Fingerprint 请求头；视频还可回传 quotedPrice（整条总价，人民币分）。提供的指纹或总价过期时返回 409，请重新读取模型并确认后再提交。明确返回 submissionAccepted=false 的价格拒绝，确认新价格后使用新的 Idempotency-Key；旧编号始终查询原回执。未提供这些可选字段的标准 API 使用提交时核定的当前售价。submissionAccepted=false 表示本次尚未接单或扣款；已受理任务按原订单报价和实际用量结算，查询原任务不能换成新请求。

生图示例：商店名 image2，接口 id 为 gpt-image-2（传 image2 也可）。密钥分类需包含「生图」或选「全部模型」。

4. 提交生成（异步）

提交成功返回任务对象：生成中为 HTTP 202，已结束为 200。是否出图/出片以任务 status 为准。

BASE="__BASE__"
KEY="fk-你的密钥"
REQUEST_ID="$(uuidgen)"

# 视频
curl "$BASE/videos" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -d '{"model":"VIDEO_MODEL_ID","prompt":"海边日落，镜头缓慢向前推进","resolution":"720p","seconds":10,"ratio":"16:9","assets":[]}'

# 文生图（resolution 用模型列表里的值，如 1K / 2K / 4K）
REQUEST_ID="$(uuidgen)"
curl "$BASE/images/generations" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -d '{"model":"gpt-image-2","prompt":"白色背景上的蓝色陶瓷杯","resolution":"1K","ratio":"1:1"}'

Idempotency-Key：16–100 位字母数字下划线或短横线。超时重试必须用同一个值，避免重复扣费。

5. 上传参考素材

curl "$BASE/assets" -H "Authorization: Bearer $KEY" \
  -F "model=MODEL_ID" -F "kind=image" -F "file=@reference.png"
# 生成时传入 "assets":["返回的素材id"]

kind 为 image / video / audio，需符合该模型能力。图生图/编辑用 POST /images/edits，参数同生图，且 assets 至少一张图。

6. 查询与下载

curl "$BASE/tasks/TASK_ID" -H "Authorization: Bearer $KEY"
curl "$BASE/tasks/TASK_ID/video?download=1" -H "Authorization: Bearer $KEY" -o result.mp4
curl "$BASE/tasks/TASK_ID/image/0?download=1" -H "Authorization: Bearer $KEY" -o result.png
curl "$BASE/tasks?limit=20" -H "Authorization: Bearer $KEY"

7. 视频超分 / 加码率

模型 id 见 /models（如 video-ai-upscale、video-bitrate-enhance、video-upscale-bitrate）。先上传原片，再提交：

curl "$BASE/assets?model=video-bitrate-enhance" -H "Authorization: Bearer $KEY" \
  -F "model=video-bitrate-enhance" -F "kind=video" -F "file=@source.mp4"

curl "$BASE/videos" -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $REQUEST_ID" \
  -d '{"model":"video-bitrate-enhance","assets":["ASSET_ID"],"processing":{"mode":"bitrate","target_resolution":"original","video_mbps":20}}'

mode：upscale / bitrate / upscale_bitrate。参数以该模型在 /models 中的说明为准；available=false 不可下单。

8. 接口一览

9. 错误码

400 参数错误 · 401 密钥无效 · 402 余额不足 · 403 密钥无权调用 · 404 模型或资源不存在 · 409 冲突/并发上限 · 413 文件过大 · 415 格式不支持 · 429 限流 · 5xx 服务异常

{"error":{"message":"说明","type":"invalid_request_error","code":"400"}}

curl "$BASE/chat/completions" -H "Authorization: Bearer $KEY" \
 -H "Content-Type: application/json" -H "Idempotency-Key: $REQUEST_ID" \
 -d '{"model":"GET /models 返回的大模型 id","messages":[{"role":"user","content":"你好"}],"max_tokens":2048}'