# YB Studio API

自托管音视频生成平台 API。TTS 由 IndexTTS-2 提供，音频驱动人像视频由 LongCat-Video-Avatar 1.5 提供。

Base URL: `https://ybstudio.cn/api`

## Authentication

Use Bearer JWT for dashboard routes, `X-API-Key` for `/v1/*`, and `X-Worker-Secret` for `/worker/*`.

## Endpoints

- `GET /admin/audit` — List Audit
- `GET /admin/orders` — List Orders
- `GET /admin/orders/export` — Export Orders
  Export the (filtered) order list as CSV. No pagination — all matches.  Selects enum columns cast to text so historical mixed-case enum values in a shared dev DB don't break ORM enum coercion (same guard as reconciliation).
- `POST /admin/orders/{order_id}/refund` — Refund Order
- `GET /admin/plans` — List All Plans
  All plans including private ones (public endpoint hides is_public=False).
- `POST /admin/plans` — Create Plan
- `PATCH /admin/plans/{plan_id}` — Update Plan
- `GET /admin/reconciliation` — Reconciliation
- `GET /admin/storage/list` — List Storage
  List one directory level (folders + files) under ``prefix``.
- `DELETE /admin/storage/object` — Delete Storage Object
  Delete a single object and record an audit entry.
- `POST /admin/storage/presign-get` — Presign Download
  Issue a short-lived GET URL for download or inline preview.
- `POST /admin/storage/presign-put` — Presign Upload
  Issue a short-lived PUT URL so the browser uploads directly to storage.
- `GET /admin/users` — List Users
- `PATCH /admin/users/{user_id}` — Update User
- `POST /admin/users/{user_id}/credits` — Adjust Credits
  Manually grant (+) or deduct (-) credits, recorded in the ledger.  Grants land in the TOPUP bucket (persist across cycles); deductions post a negative EXPIRE entry so they don't roll over either.
- `POST /auth/login` — Login
- `GET /auth/me` — Me
- `POST /auth/refresh` — Refresh
- `POST /auth/register` — Register
- `GET /billing/balance` — Get Balance
- `GET /billing/credit-packs` — List Credit Packs
- `POST /billing/dev/manual-confirm` — Dev Manual Confirm
  DEV-ONLY: simulate a manual-provider payment for one's own order.  Signs a fake notify body and drives the same fulfillment path. Enabled only when the manual provider is enabled (disable in production).
- `GET /billing/ledger` — Get Ledger
- `GET /billing/ledger/export` — Export Ledger
  Export the (filtered) credit ledger as CSV. No pagination — all matches.
- `POST /billing/notify/alipay` — Notify Alipay
- `POST /billing/notify/manual` — Notify Manual
- `POST /billing/notify/wechat` — Notify Wechat
- `GET /billing/orders` — List Orders
- `POST /billing/orders` — Create Order
- `GET /billing/orders/export` — Export Orders
  Export the (filtered) order history as CSV.
- `GET /billing/orders/{order_id}` — Get Order
- `GET /billing/plans` — List Plans
- `POST /billing/subscribe` — Subscribe
  Provision a FREE plan immediately.  Paid plans must go through /billing/orders + payment; this endpoint rejects them so paid entitlements are only ever granted after a verified payment.
- `GET /billing/subscription` — Get Subscription
- `POST /billing/subscription/auto-renew` — Set Auto Renew
  Enable or disable auto-renewal for the current subscription.  Disabling leaves the current paid period intact; the subscription simply won't be auto-charged and will lapse to free at period end.
- `POST /billing/topup` — Create Topup
  Buy a one-off credit pack. Credits land in the TOPUP bucket (persist across billing cycles) after payment is confirmed.
- `GET /docs/llms-full.txt` — Llms Full Txt
- `GET /docs/llms.txt` — Llms Txt
- `GET /docs/openapi.md` — Openapi Markdown
- `GET /health` — Health
- `GET /keys` — List Keys
- `POST /keys` — Create Key
- `DELETE /keys/{key_id}` — Revoke Key
- `POST /v1/avatar` — Create Avatar
- `POST /v1/avatar/from-text` — Create Avatar From Text
  One call: text -> internal TTS -> LongCat avatar video.  Priced as an avatar job (the dominant cost); the internal TTS step is performed by the video worker pipeline and reflected at settlement.
- `GET /v1/jobs` — List Jobs
- `GET /v1/jobs/{job_id}` — Get Job
- `GET /v1/jobs/{job_id}/result` — Get Job Result
- `POST /v1/tts` — Create Tts
- `POST /v1/uploads` — Create Upload Url
  Issue a presigned PUT URL for uploading reference audio/images.
- `POST /worker/claim` — Claim Job
- `POST /worker/{job_id}/complete` — Complete Job
- `POST /worker/{job_id}/fail` — Fail Job
- `POST /worker/{job_id}/progress` — Report Progress