Open API 文档

独立生成接口。与网站账号/代理体系无关。鉴权使用 API Key；积分与价格由运营在 /admin 配置。

Base URL

Auth

Authorization: Bearer fxk_xxxxxxxx
# 或
X-API-Key: fxk_xxxxxxxx

效果目录（按分类）

创建任务必须传 template_id。四类：图片 · 视频 · 自定义图片 · 自定义视频（对应 price_group: fixed_image / sqs_video / custom_i2i / custom_i2v）。

loading…

能力范围

图片：GPU 固定效果（grtkniv / bs_dispatch）
视频：AWS SQS（dispatch_*）
自定义图片 custom_i2i / 自定义视频 custom_i2v
不含 combo、换脸 faceswap

流程

1. GET  /catalog 或 GET /v1/effects   ← 查 template_id + name_zh/name_en + price
2. POST /v1/upload                    ← multipart 字段名 image
3. POST /v1/tasks                     ← body 必填 template_id + image_url
4. GET  /v1/tasks/:id                 ← poll 直到 completed|failed
   → data.output_url

GET /v1/effects 响应字段

字段	说明
`template_id`	效果 ID，创建任务时原样传入
`name_zh`	中文名称
`name_en`	英文名称
`task_type`	grtkniv / bs_dispatch / dispatch 等
`is_video`	是否视频效果
`price`	API 积分价格
`price_group`	fixed_image（图片）/ sqs_video（视频）/ custom_i2i / custom_i2v
`settings_schema`	可选；该效果支持的参数白名单

POST /v1/tasks 请求参数

字段	必填	说明
`template_id`	是	效果 ID，见上方分类目录
`image_url`	是	上传接口返回的 `data.url`
`prompt`	否	自定义图片/视频（custom_i2i / custom_i2v）用
`settings`	否	对象；须符合该效果的 `settings_schema`

{
  "template_id": "grtkniv_naked",
  "image_url": "/static/uploads/....jpg",
  "prompt": "",
  "settings": {}
}

Endpoints

GET  /catalog                         (公开，免 Key)
GET  /v1/effects                      (需 Key)
POST /v1/upload                       (≤12MB; 返回 /static/uploads/...)
POST /v1/tasks                        (必填 template_id + image_url；可带 Idempotency-Key)
GET  /v1/tasks?status=&limit=&offset=
GET  /v1/tasks/:id
GET  /v1/estimated-time?template_id=
GET  /v1/account
GET  /v1/account/credits
GET  /v1/account/usage?days=30

安全要点

image_url 只能是 POST /v1/upload 返回的 /static/uploads/...（防 SSRF）
output_url 为签名短链 /results/...?exp=&sig=（默认 1h）；也可用 Bearer Key 拉结果
创建任务可带 Idempotency-Key 头，24h 内重试返回同一响应
Webhook（admin 配置）：任务 completed/failed 时 POST；头 X-OpenAPI-Signature: sha256=...
可选日配额 daily_quota + 每分钟限流 rate_per_min

Example

Errors

code	meaning
unauthorized	缺/错 Key 或结果签名无效
insufficient_credits	余额不足
quota_exceeded	日配额用尽
invalid_image_url	非本站 upload 路径
not_priced	未配置价格
invalid_effect	效果不可用
upstream_failed	上游生成失败
rate_limited	超限流

Open API Docs

Catalog grouped into Image / Video / Custom Image / Custom Video. image_url must come from upload. Results use signed URLs. Use Idempotency-Key on create. Optional webhooks on terminal status.