{
  "openapi": "3.1.0",
  "info": {
    "title": "tokencoup Gateway API",
    "version": "0.8.0",
    "description": "OpenAI-compatible proxy in front of Baidu Qianfan. Edition and mode are encoded in the path. Pre-launch: the API subdomain resolves but every request returns HTTP 503 with error.type=not_live; no traffic is served. v0.3 adds GET /v1/usage, GET /v1/models and buffered SSE. v0.4 meters token counts from the upstream usage field (JSON and SSE), falls back to a flagged estimate, and adds idempotency, atomic quota debits and UTC monthly billing periods. Prices remain placeholders. The video category (/vod/*) is a separate, fail-closed surface: async Baidu VOD v3 tasks, metered per task (never in tokens) in a separate ledger, with no tariff yet so it produces no billing. v0.5 adds the sibling /video/* prefix (Qianfan native video generation, reusing your Qianfan key): a third rate-limit bucket (rlq:), bidirectional key isolation against the VOD registry, and the same task-based metering. v0.6 adds the /eos/* experimental third-party proxy as a fourth category: strict key-to-site binding, a hardcoded model allowlist, an independent rate-limit bucket and a separate usage ledger that records upstream token counts but never produces a bill. v0.7 adds trial quota: a gated, never-billed lane for callers without a registered credential (off by default; per-key hourly/daily and global daily caps; its own trial_ledger table). v0.8 adds the /account/* self-serve surface (register, session, gateway-key lifecycle, per-account usage) as a separate prefix with its own session authentication. It is DEFAULT OFF: no personal data is accepted until TOKENCOUP_ACCOUNTS_ENABLED=1, which is gated on unresolved data-residency and entity items in the compliance plan. When disabled these endpoints return 404.",
    "x-pricing": {
      "status": "catalogue_only",
      "currency_note": "cn edition prices are CNY per 1k tokens; no customer-facing price is published yet.",
      "layers": {
        "catalogue": "Baidu Qianfan public price list (source dated, per model)",
        "sell": "NOT DEFINED - no markup layer exists; nothing here is a quote to customers"
      },
      "note": "Cost, discount and margin data are not part of this API or this repository.",
      "detail_file": "/cn-pricing.html",
      "detail_json": "/cn_pricing.json",
      "missing_models_are_not_priced": true
    },
    "contact": {
      "name": "tokencoup docs",
      "url": "https://tokencoup.com/intl/en/docs.html"
    }
  },
  "servers": [
    {
      "url": "https://api.tokencoup.com",
      "description": "Reserved production endpoint - currently returns HTTP 503 not_live (no API traffic)"
    },
    {
      "url": "http://127.0.0.1:8081",
      "description": "Local reference server (mock mode by default)"
    }
  ],
  "paths": {
    "/intl/a/v1/chat/completions": {
      "post": {
        "tags": [
          "INTL / Mode A"
        ],
        "summary": "intl Mode A — chat completions (Qianfan passthrough)",
        "description": "Bring your own Qianfan key; the key edition must match the serving edition. Set stream=true for a text/event-stream response.",
        "operationId": "intlAChatCompletions",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "ProviderKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "description": "Optional idempotency key. Reusing the same value on a retry does not write a second ledger row or debit the quota twice. The gateway generates one when omitted.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upstream Qianfan response, passed through unchanged. JSON by default; text/event-stream when stream=true.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "SSE data: chunks terminated by `data: [DONE]`. v0.3 uses buffered passthrough (no chunk-by-chunk flush)."
                }
              }
            }
          },
          "400": {
            "description": "edition_unknown — missing or invalid edition/mode path prefix",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "quota_exceeded — Mode B token quota exhausted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "mode_B_not_allowed_on_cn / mode_B_not_allowed_on_intl / missing_provider_key / key_edition_unknown / key_edition_mismatch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_endpoint — GET path is not /v1/usage or /v1/models",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — plan RPM exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "service_unavailable — upstream unreachable (Mode B cancelled 2026-11-13; not a resale-pool status)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/intl/a/v1/usage": {
      "get": {
        "tags": [
          "INTL / Mode A"
        ],
        "summary": "Measured local usage — no upstream call, no billing",
        "description": "Values come from the gateway's subscriptions + usage_ledger tables and from gateway/plans.py. Authenticated and rate-limited, but never metered. v0.4: token counts use the upstream usage field when available; otherwise they fall back to len(body)/4 and are flagged estimated. tokens_measured / tokens_estimated / estimated_calls expose the split. Neither figure is a final invoice.",
        "operationId": "intlAUsage",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "ProviderKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Measured usage snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Usage"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "mode_B_not_allowed_on_cn / mode_B_not_allowed_on_intl / missing_provider_key / key_edition_unknown / key_edition_mismatch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — plan RPM exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/intl/a/v1/models": {
      "get": {
        "tags": [
          "INTL / Mode A"
        ],
        "summary": "Upstream model catalogue passthrough",
        "description": "Relayed to the Qianfan upstream under the same edition/key checks. Verified 2026-11-12: the public endpoint returns HTTP 200 with 17 models, 14 carrying published per-token prices, without authentication. tokencoup does not rewrite the catalogue; a dated snapshot is published on the homepage. Directory prices are not a settlement commitment. Mock mode makes no network call and returns models: [].",
        "operationId": "intlAModels",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "ProviderKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Upstream model list, passed through unchanged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "edition_unknown — missing or invalid edition/mode path prefix",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "quota_exceeded — Mode B token quota exhausted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "mode_B_not_allowed_on_cn / mode_B_not_allowed_on_intl / missing_provider_key / key_edition_unknown / key_edition_mismatch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_endpoint — GET path is not /v1/usage or /v1/models",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — plan RPM exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "service_unavailable — upstream unreachable (Mode B cancelled 2026-11-13; not a resale-pool status)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/cn/a/v1/chat/completions": {
      "post": {
        "tags": [
          "CN / Mode A"
        ],
        "summary": "cn Mode A — chat completions (Qianfan passthrough)",
        "description": "Bring your own Qianfan key; the key edition must match the serving edition. Set stream=true for a text/event-stream response.",
        "operationId": "cnAChatCompletions",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "ProviderKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "description": "Optional idempotency key. Reusing the same value on a retry does not write a second ledger row or debit the quota twice. The gateway generates one when omitted.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upstream Qianfan response, passed through unchanged. JSON by default; text/event-stream when stream=true.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string",
                  "description": "SSE data: chunks terminated by `data: [DONE]`. v0.3 uses buffered passthrough (no chunk-by-chunk flush)."
                }
              }
            }
          },
          "400": {
            "description": "edition_unknown — missing or invalid edition/mode path prefix",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "quota_exceeded — Mode B token quota exhausted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "mode_B_not_allowed_on_cn / mode_B_not_allowed_on_intl / missing_provider_key / key_edition_unknown / key_edition_mismatch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_endpoint — GET path is not /v1/usage or /v1/models",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — plan RPM exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "service_unavailable — upstream unreachable (Mode B cancelled 2026-11-13; not a resale-pool status)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/cn/a/v1/usage": {
      "get": {
        "tags": [
          "CN / Mode A"
        ],
        "summary": "Measured local usage — no upstream call, no billing",
        "description": "Values come from the gateway's subscriptions + usage_ledger tables and from gateway/plans.py. Authenticated and rate-limited, but never metered. v0.4: token counts use the upstream usage field when available; otherwise they fall back to len(body)/4 and are flagged estimated. tokens_measured / tokens_estimated / estimated_calls expose the split. Neither figure is a final invoice.",
        "operationId": "cnAUsage",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "ProviderKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Measured usage snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Usage"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "mode_B_not_allowed_on_cn / mode_B_not_allowed_on_intl / missing_provider_key / key_edition_unknown / key_edition_mismatch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — plan RPM exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/cn/a/v1/models": {
      "get": {
        "tags": [
          "CN / Mode A"
        ],
        "summary": "Upstream model catalogue passthrough",
        "description": "Relayed to the Qianfan upstream under the same edition/key checks. Verified 2026-11-12: the public endpoint returns HTTP 200 with 17 models, 14 carrying published per-token prices, without authentication. tokencoup does not rewrite the catalogue; a dated snapshot is published on the homepage. Directory prices are not a settlement commitment. Mock mode makes no network call and returns models: [].",
        "operationId": "cnAModels",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "ProviderKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Upstream model list, passed through unchanged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "edition_unknown — missing or invalid edition/mode path prefix",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "quota_exceeded — Mode B token quota exhausted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "mode_B_not_allowed_on_cn / mode_B_not_allowed_on_intl / missing_provider_key / key_edition_unknown / key_edition_mismatch",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_endpoint — GET path is not /v1/usage or /v1/models",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — plan RPM exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "service_unavailable — upstream unreachable (Mode B cancelled 2026-11-13; not a resale-pool status)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/vod/v3/aigc/text_to_video": {
      "post": {
        "tags": [
          "VIDEO / Baidu VOD v3"
        ],
        "summary": "Video generation (Baidu VOD v3) — async task, metered per task",
        "description": "Separate category, not an edition of the text API: single-segment prefix, different upstream (Baidu VOD v3), metered per task and never in tokens. Creating a task costs real money upstream, so an idempotency replay is resolved BEFORE forwarding — reusing the same X-Request-Id returns the cached taskId with duplicate=true and makes zero new upstream calls. Video is recorded in a separate ledger (video_task_ledger) and never decrements the token quota. No VOD tariff exists yet: billable_units is recorded but no amount is produced (priced=false, billing_status=no_tariff). Pre-launch and fail-closed: every request returns 403 until a VOD key is registered in secrets/vod_keys.json. Upstream default is https://vod.bj.baidubce.com:443 (the documented example port 8301 is not reachable from the public internet). The Bearer scheme is not yet confirmed on that host — unauthenticated requests, the documented bce-v3/ALTAK- form and the vod-v3 form all returned the same BceSignatureValidateException, so do not bill or promise this category until a real key returns 200.",
        "operationId": "vodAigcProxy",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "VodKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "description": "Idempotency key, resolved before forwarding. Reusing the same value returns the cached taskId and creates no new upstream task. Generated by the gateway when omitted (a generated value cannot be reused across retries).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VodTaskRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Task created. The upstream returns a taskId; poll GET /vod/v3/tasks/{taskId}. Metered as one task (billable_units=1), never in tokens.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "200": {
            "description": "Read-only endpoint result, or an idempotent replay of a previously created task (duplicate=true, no new upstream call).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "vod_key_unregistered — no VOD key registered, or the key is also registered as a Qianfan key (registries are mutually exclusive)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_vod_endpoint — path not on Baidu's API-Key permission list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — video bucket (2 requests / 60 s by default) exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/vod/v3/aigc/image_to_video": {
      "post": {
        "tags": [
          "VIDEO / Baidu VOD v3"
        ],
        "summary": "Video generation (Baidu VOD v3) — async task, metered per task",
        "description": "Separate category, not an edition of the text API: single-segment prefix, different upstream (Baidu VOD v3), metered per task and never in tokens. Creating a task costs real money upstream, so an idempotency replay is resolved BEFORE forwarding — reusing the same X-Request-Id returns the cached taskId with duplicate=true and makes zero new upstream calls. Video is recorded in a separate ledger (video_task_ledger) and never decrements the token quota. No VOD tariff exists yet: billable_units is recorded but no amount is produced (priced=false, billing_status=no_tariff). Pre-launch and fail-closed: every request returns 403 until a VOD key is registered in secrets/vod_keys.json. Upstream default is https://vod.bj.baidubce.com:443 (the documented example port 8301 is not reachable from the public internet). The Bearer scheme is not yet confirmed on that host — unauthenticated requests, the documented bce-v3/ALTAK- form and the vod-v3 form all returned the same BceSignatureValidateException, so do not bill or promise this category until a real key returns 200.",
        "operationId": "vodAigcProxy",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "VodKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "description": "Idempotency key, resolved before forwarding. Reusing the same value returns the cached taskId and creates no new upstream task. Generated by the gateway when omitted (a generated value cannot be reused across retries).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VodTaskRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Task created. The upstream returns a taskId; poll GET /vod/v3/tasks/{taskId}. Metered as one task (billable_units=1), never in tokens.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "200": {
            "description": "Read-only endpoint result, or an idempotent replay of a previously created task (duplicate=true, no new upstream call).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "vod_key_unregistered — no VOD key registered, or the key is also registered as a Qianfan key (registries are mutually exclusive)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_vod_endpoint — path not on Baidu's API-Key permission list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — video bucket (2 requests / 60 s by default) exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/vod/v3/aigc/text_to_image": {
      "post": {
        "tags": [
          "VIDEO / Baidu VOD v3"
        ],
        "summary": "Video generation (Baidu VOD v3) — async task, metered per task",
        "description": "Separate category, not an edition of the text API: single-segment prefix, different upstream (Baidu VOD v3), metered per task and never in tokens. Creating a task costs real money upstream, so an idempotency replay is resolved BEFORE forwarding — reusing the same X-Request-Id returns the cached taskId with duplicate=true and makes zero new upstream calls. Video is recorded in a separate ledger (video_task_ledger) and never decrements the token quota. No VOD tariff exists yet: billable_units is recorded but no amount is produced (priced=false, billing_status=no_tariff). Pre-launch and fail-closed: every request returns 403 until a VOD key is registered in secrets/vod_keys.json. Upstream default is https://vod.bj.baidubce.com:443 (the documented example port 8301 is not reachable from the public internet). The Bearer scheme is not yet confirmed on that host — unauthenticated requests, the documented bce-v3/ALTAK- form and the vod-v3 form all returned the same BceSignatureValidateException, so do not bill or promise this category until a real key returns 200.",
        "operationId": "vodAigcProxy",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "VodKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "description": "Idempotency key, resolved before forwarding. Reusing the same value returns the cached taskId and creates no new upstream task. Generated by the gateway when omitted (a generated value cannot be reused across retries).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VodTaskRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Task created. The upstream returns a taskId; poll GET /vod/v3/tasks/{taskId}. Metered as one task (billable_units=1), never in tokens.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "200": {
            "description": "Read-only endpoint result, or an idempotent replay of a previously created task (duplicate=true, no new upstream call).",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "vod_key_unregistered — no VOD key registered, or the key is also registered as a Qianfan key (registries are mutually exclusive)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_vod_endpoint — path not on Baidu's API-Key permission list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — video bucket (2 requests / 60 s by default) exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/vod/v3/tasks/{taskId}": {
      "get": {
        "tags": [
          "VIDEO / Baidu VOD v3"
        ],
        "summary": "Poll a video task (read-only, not metered)",
        "description": "Relayed to Baidu VOD. Read-only: authenticated and rate-limited, but never metered and never billed.",
        "operationId": "vodTaskStatus",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "VodKey": []
          }
        ],
        "parameters": [
          {
            "name": "taskId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Upstream task status, passed through unchanged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "vod_key_unregistered — no VOD key registered, or the key is also registered as a Qianfan key (registries are mutually exclusive)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_vod_endpoint — path not on Baidu's API-Key permission list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — video bucket (2 requests / 60 s by default) exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/video/generations/qianfan-video": {
      "post": {
        "tags": [
          "VIDEO / Qianfan native"
        ],
        "summary": "Qianfan native video generation — async task, metered per task",
        "description": "Second video category, sibling of /vod/*: single-segment prefix /video/*, upstream qianfan.baidubce.com/beta/video/…, and it reuses the SAME Bearer key registry as the Qianfan chat API (Mode A). Auth verified against the live endpoint 2026-11-13 with a domestic key: invalid credentials return 401 invalid_iam_token; valid keys reach the business layer (400 invalid_video_generation_argument on a bad body). Isolation is bidirectional: a VOD-registered key is rejected here (qf_video_key_unregistered) and a Qianfan key is rejected by /vod — the registry, not the key shape, decides the category. Edition-restricted: only domestic-edition keys are accepted; the international beta path is unverified, so it fails closed. Rate limit lives in a third bucket rlq: (default 2 requests / 60 s; override with TOKENCOUP_QF_VIDEO_RPM), independent of the text (rl:) and VOD (rlv:) buckets. Creating a task is metered in video_task_ledger as one task — the upstream usage block (duration/resolution/total_tokens) is recorded as metadata only and never summed into the token ledger. Idempotency replay resolves BEFORE forwarding: reusing the same X-Request-Id returns the cached task_id with duplicate=true and makes zero new upstream calls. No tariff exists yet: priced=false, billing_status=no_tariff.",
        "operationId": "qfVideoGenerations",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "ProviderKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "description": "Idempotency key, resolved before forwarding. Reusing the same value returns the cached task_id and creates no new upstream task. Generated by the gateway when omitted (a generated value cannot be reused across retries).",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QfVideoRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Create: task created — the response carries task_id and a usage block (duration/resolution/total_tokens). Poll with GET /video/generations/qianfan-video/fireseries?task_id=. Read-only endpoints (query/list) pass the upstream response through. Metered as one task (billable_units=1), never in tokens. An idempotent replay (same X-Request-Id) returns the cached task_id with duplicate=true and zero new upstream calls.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "invalid_video_generation_argument — upstream rejected the request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "qf_video_key_unregistered — the Bearer key is not in the Qianfan registry, or is a VOD-registered key (registries are mutually exclusive); qf_video_key_edition — international-edition keys are rejected (beta endpoints verified on qianfan.baidubce.com only)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_qf_video_endpoint — path not in the Qianfan video whitelist (create/query/list)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — Qianfan video bucket rlq: (2 requests / 60 s by default, independent of the text and VOD buckets)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/video/generations/qianfan-video/fireseries": {
      "get": {
        "tags": [
          "VIDEO / Qianfan native"
        ],
        "summary": "Poll a Qianfan video task (read-only, not metered)",
        "description": "Relayed to GET qianfan.baidubce.com/beta/video/generations/qianfan-video/fireseries with the caller-supplied task_id query parameter. Read-only: authenticated and rate-limited (rlq: bucket), never metered, never billed, and does not touch the video_task_ledger.",
        "operationId": "qfVideoTaskStatus",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "ProviderKey": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Upstream task status, passed through unchanged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "invalid_video_generation_argument — upstream rejected the request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "qf_video_key_unregistered — the Bearer key is not in the Qianfan registry, or is a VOD-registered key (registries are mutually exclusive); qf_video_key_edition — international-edition keys are rejected (beta endpoints verified on qianfan.baidubce.com only)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_qf_video_endpoint — path not in the Qianfan video whitelist (create/query/list)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — Qianfan video bucket rlq: (2 requests / 60 s by default, independent of the text and VOD buckets)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/video/generations/qianfan-video/m-series/list": {
      "get": {
        "tags": [
          "VIDEO / Qianfan native"
        ],
        "summary": "List Qianfan video tasks (read-only, not metered)",
        "description": "Relayed to GET qianfan.baidubce.com/beta/video/generations/qianfan-video/m-series/list. Read-only: authenticated and rate-limited (rlq: bucket), never metered.",
        "operationId": "qfVideoTaskList",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "ProviderKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Upstream task list, passed through unchanged",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "invalid_video_generation_argument — upstream rejected the request body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "qf_video_key_unregistered — the Bearer key is not in the Qianfan registry, or is a VOD-registered key (registries are mutually exclusive); qf_video_key_edition — international-edition keys are rejected (beta endpoints verified on qianfan.baidubce.com only)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_qf_video_endpoint — path not in the Qianfan video whitelist (create/query/list)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — Qianfan video bucket rlq: (2 requests / 60 s by default, independent of the text and VOD buckets)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/eos/v1/chat/completions": {
      "post": {
        "tags": [
          "EOS / experimental proxy"
        ],
        "summary": "Experimental OpenAI-compatible chat proxy — usage recorded, never billed",
        "description": "Fourth category, wired in on 2026-11-14. Neither Qianfan nor the official VOD API: an experimental third-party one-api/new-api family proxy at eos-{ca,sg}.aigc.exp.bcevod.com. Keys are strictly bound to one site (US key to ca, SG key to sg); every cross-site combination returned 40100 upstream, so the gateway never fails over to another site. The upstream /v1/models catalogue is retired (40400) and there is no billing/usage query endpoint (five candidate paths all 404): model discovery is a hardcoded allowlist and usage true values go to a separate eos_usage_ledger for observability only. Never billed, never priced, never debited from the token quota — no tariff, no invoice, no SLA. Fail-closed: every request returns 403 until a key is active in secrets/eos_keys.json.",
        "operationId": "eosChatCompletions",
        "security": [
          {
            "GatewayKey": []
          },
          {
            "EosKey": []
          }
        ],
        "parameters": [
          {
            "name": "X-Request-Id",
            "in": "header",
            "required": false,
            "description": "Idempotency key, resolved before forwarding. A replay returns duplicate=true and makes zero upstream calls; response bodies are never stored.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EosChatRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Upstream OpenAI-compatible chat completion (or buffered SSE when stream=true), or an idempotent replay with duplicate=true.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "model_not_allowed — model not on the hardcoded eos allowlist; the upstream catalogue endpoint is retired",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "gateway_auth_failed — missing, invalid or revoked X-Gateway-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "eos_key_unregistered / eos_site_unregistered — key not active in secrets/eos_keys.json, also registered as a Qianfan/VOD key, or its bound site has no route (cross-site fallback is forbidden). Also the trial-quota codes for callers without a registered credential: trial_disabled (default), trial_model_not_allowed, trial_category_not_allowed, trial_rate_limited (hourly cap), trial_quota_exhausted (daily or global cap)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "unknown_eos_endpoint — only POST /eos/v1/chat/completions is exposed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "rate_limited — independent eos bucket (10 requests / 60 s by default) exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/account/v1/accounts": {
      "post": {
        "summary": "Register an account",
        "tags": [
          "Accounts (R1, default off)"
        ],
        "description": "Feature may be disabled (default). When disabled every endpoint returns 404 accounts_disabled; no personal data is accepted.",
        "responses": {
          "201": {
            "description": "Created (account_id, normalized email)"
          },
          "400": {
            "description": "Normalized error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountError"
                }
              }
            }
          },
          "409": {
            "description": "Normalized error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountError"
                }
              }
            }
          },
          "404": {
            "description": "Normalized error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountError"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountRegister"
              }
            }
          }
        }
      }
    },
    "/account/v1/sessions": {
      "post": {
        "summary": "Log in (returns a one-time session token + HttpOnly cookie)",
        "tags": [
          "Accounts (R1, default off)"
        ],
        "description": "Feature may be disabled (default). When disabled every endpoint returns 404 accounts_disabled; no personal data is accepted.",
        "responses": {
          "200": {
            "description": "Session created"
          },
          "401": {
            "description": "Normalized error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountError"
                }
              }
            }
          },
          "404": {
            "description": "Normalized error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountError"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountLogin"
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Log out (revoke current session)",
        "tags": [
          "Accounts (R1, default off)"
        ],
        "description": "Feature may be disabled (default). When disabled every endpoint returns 404 accounts_disabled; no personal data is accepted.",
        "responses": {
          "200": {
            "description": "Logged out"
          },
          "401": {
            "description": "Normalized error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountError"
                }
              }
            }
          }
        },
        "security": [
          {
            "SessionToken": []
          }
        ]
      }
    },
    "/account/v1/keys": {
      "get": {
        "summary": "List own gateway keys (never returns plaintext)",
        "tags": [
          "Accounts (R1, default off)"
        ],
        "description": "Feature may be disabled (default). When disabled every endpoint returns 404 accounts_disabled; no personal data is accepted.",
        "responses": {
          "200": {
            "description": "Key list"
          },
          "401": {
            "description": "Normalized error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountError"
                }
              }
            }
          }
        },
        "security": [
          {
            "SessionToken": []
          }
        ]
      },
      "post": {
        "summary": "Create a gateway key (plaintext shown once)",
        "tags": [
          "Accounts (R1, default off)"
        ],
        "description": "Feature may be disabled (default). When disabled every endpoint returns 404 accounts_disabled; no personal data is accepted.",
        "responses": {
          "201": {
            "description": "Key created"
          },
          "400": {
            "description": "Normalized error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountError"
                }
              }
            }
          },
          "401": {
            "description": "Normalized error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountError"
                }
              }
            }
          }
        },
        "security": [
          {
            "SessionToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountKeyCreate"
              }
            }
          }
        }
      }
    },
    "/account/v1/keys/{keyId}": {
      "delete": {
        "summary": "Revoke own key",
        "tags": [
          "Accounts (R1, default off)"
        ],
        "description": "Feature may be disabled (default). When disabled every endpoint returns 404 accounts_disabled; no personal data is accepted.",
        "responses": {
          "200": {
            "description": "Revoked"
          },
          "401": {
            "description": "Normalized error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountError"
                }
              }
            }
          },
          "404": {
            "description": "Normalized error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountError"
                }
              }
            }
          }
        },
        "security": [
          {
            "SessionToken": []
          }
        ],
        "parameters": [
          {
            "name": "keyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Own key_id (k_…); another account's key returns 404."
          }
        ]
      }
    },
    "/account/v1/usage": {
      "get": {
        "summary": "Usage summary across own keys",
        "tags": [
          "Accounts (R1, default off)"
        ],
        "description": "Feature may be disabled (default). When disabled every endpoint returns 404 accounts_disabled; no personal data is accepted.",
        "responses": {
          "200": {
            "description": "Per-key quota and ledger totals"
          },
          "401": {
            "description": "Normalized error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountError"
                }
              }
            }
          }
        },
        "security": [
          {
            "SessionToken": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "GatewayKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Gateway-Key",
        "description": "tokencoup gateway API key (rf_…). Required on every request."
      },
      "ProviderKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Your own Qianfan key. Mode A only; edition must match."
      },
      "VodKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Vod-Key",
        "description": "Your own Baidu VOD (video generation) key. Video category only. Registered separately from Qianfan keys; the two registries are mutually exclusive, so a key registered as a Qianfan key is rejected by /vod. String format cannot decide the category — Baidu's own VOD example key is bce-v3/ALTAK-…, identical in shape to a Qianfan key."
      },
      "EosKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Eos-Key",
        "description": "Your own eos experimental-gateway key (also accepted as Authorization: Bearer). Must be active in secrets/eos_keys.json and strictly bound to one site (ca for the US key, sg for the SG key). Mutually exclusive with the Qianfan and VOD registries."
      },
      "SessionToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "R1 account session token (sess_…), returned once by POST /account/v1/sessions. Sent as Authorization: Bearer, or carried in the HttpOnly+Secure tc_session cookie. Never in a URL query parameter, never in localStorage. Server stores only its sha256 and enforces a TTL."
      }
    },
    "schemas": {
      "AccountRegister": {
        "type": "object",
        "required": [
          "email",
          "password"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "description": "Normalized to lowercase; unique."
          },
          "password": {
            "type": "string",
            "minLength": 8,
            "maxLength": 128,
            "description": "Never stored in plaintext (PBKDF2-HMAC-SHA256 + per-account random salt)."
          }
        }
      },
      "AccountLogin": {
        "type": "object",
        "required": [
          "email",
          "password"
        ],
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "password": {
            "type": "string"
          }
        }
      },
      "AccountKeyCreate": {
        "type": "object",
        "properties": {
          "plan": {
            "type": "string",
            "enum": [
              "free",
              "pro",
              "scale"
            ],
            "default": "free",
            "description": "Placeholder plan names; real pricing is not published yet."
          }
        }
      },
      "AccountError": {
        "type": "object",
        "required": [
          "error",
          "request_id"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "example": "invalid_credentials"
              },
              "message": {
                "type": "string",
                "description": "Stable, non-sensitive text; never contains a stack trace or internal field."
              }
            }
          },
          "request_id": {
            "type": "string"
          }
        }
      },
      "ChatRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "properties": {
          "model": {
            "type": "string",
            "example": "ernie-4.0-8k"
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "role",
                "content"
              ],
              "properties": {
                "role": {
                  "type": "string",
                  "enum": [
                    "system",
                    "user",
                    "assistant"
                  ]
                },
                "content": {
                  "type": "string"
                }
              }
            }
          },
          "temperature": {
            "type": "number",
            "example": 0.7
          },
          "stream": {
            "type": "boolean",
            "example": false,
            "description": "true returns text/event-stream. Buffered passthrough; chunk-by-chunk flush is not implemented. If the upstream emits a final SSE chunk with usage, those tokens are metered as real; otherwise the fallback is flagged estimated."
          }
        }
      },
      "Usage": {
        "type": "object",
        "required": [
          "key_id",
          "plan",
          "token_quota",
          "token_used_billable",
          "token_remaining",
          "rpm_limit",
          "ledger_calls",
          "ledger_tokens",
          "tokens_measured",
          "tokens_estimated",
          "estimated_calls",
          "billed_amount_usd"
        ],
        "properties": {
          "key_id": {
            "type": "string",
            "example": "k_1a2b3c4d"
          },
          "plan": {
            "type": "string",
            "enum": [
              "free",
              "pro",
              "scale"
            ]
          },
          "currency": {
            "type": "string",
            "example": "USD"
          },
          "period_start": {
            "type": "string",
            "format": "date-time"
          },
          "period_end": {
            "type": "string",
            "format": "date-time",
            "description": "UTC monthly period end (exclusive); quota resets on rollover"
          },
          "token_quota": {
            "type": "integer",
            "example": 5000000
          },
          "token_used_billable": {
            "type": "integer",
            "description": "Mode B billable tokens only — not equal to ledger_tokens"
          },
          "token_remaining": {
            "type": "integer"
          },
          "rpm_limit": {
            "type": "integer",
            "example": 600
          },
          "ledger_calls": {
            "type": "integer",
            "description": "All recorded calls (Mode A and Mode B)"
          },
          "ledger_tokens": {
            "type": "integer",
            "description": "All recorded tokens = tokens_measured + tokens_estimated"
          },
          "tokens_measured": {
            "type": "integer",
            "description": "Tokens backed by the upstream usage field (settlement-grade shape)"
          },
          "tokens_estimated": {
            "type": "integer",
            "description": "Tokens from the len(body)/4 fallback — not settlement-grade"
          },
          "estimated_calls": {
            "type": "integer",
            "description": "Number of calls whose token count is estimated"
          },
          "billed_amount_usd": {
            "type": "number"
          },
          "overage_usd_per_1k_tokens": {
            "type": "number",
            "example": 0.002
          },
          "source": {
            "type": "string",
            "example": "local subscriptions + usage_ledger (measured locally; token counts use upstream usage when available, otherwise flagged estimated)"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "example": "quota_exceeded"
          },
          "detail": {
            "type": "string"
          }
        }
      },
      "EosChatRequest": {
        "type": "object",
        "required": [
          "model",
          "messages"
        ],
        "description": "OpenAI-compatible chat body forwarded verbatim to the key-bound eos site. The model ID is checked against a hardcoded allowlist: the upstream /v1/models catalogue has been retired (40400), so model discovery is impossible.",
        "properties": {
          "model": {
            "type": "string",
            "enum": [
              "gemini-2.5-flash",
              "gemini-2.5-flash-lite",
              "gemini-2.5-flash-pro",
              "gemini-2.5-flash-image",
              "glm-5.2",
              "glm-5.1",
              "kimi-k3"
            ],
            "example": "gemini-2.5-flash"
          },
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "role",
                "content"
              ],
              "properties": {
                "role": {
                  "type": "string",
                  "enum": [
                    "system",
                    "user",
                    "assistant"
                  ]
                },
                "content": {
                  "type": "string"
                }
              }
            }
          },
          "stream": {
            "type": "boolean",
            "example": false,
            "description": "true returns text/event-stream buffered passthrough. The last SSE chunk carrying usage supplies the recorded token counts; no usage means no estimate and no ledger row."
          }
        }
      },
      "VodTaskRequest": {
        "type": "object",
        "description": "Passed through to Baidu VOD v3 after path normalisation. Field names follow Baidu's API (model plus a model-specific input object, e.g. modelP40TaskInput). tokencoup does not rewrite the body.",
        "required": [
          "model"
        ],
        "properties": {
          "model": {
            "type": "string",
            "example": "P40",
            "description": "Video model ID (for example P40, K16, VQ1). Case-sensitive; confirm the available IDs in the Baidu VOD console."
          },
          "modelP40TaskInput": {
            "type": "object",
            "description": "Model-specific parameters. The gateway reads only model / duration / resolution / aspectRatio from here as cost drivers; prompt and every other field are forwarded verbatim and never persisted.",
            "properties": {
              "prompt": {
                "type": "string",
                "example": "a cat surfing a wave, cinematic"
              },
              "duration": {
                "type": "integer",
                "example": 5
              },
              "resolution": {
                "type": "string",
                "example": "540p"
              },
              "aspectRatio": {
                "type": "string",
                "example": "16:9"
              }
            }
          }
        }
      },
      "QfVideoRequest": {
        "type": "object",
        "description": "Passed through to qianfan.baidubce.com/beta/video/generations/qianfan-video after path normalisation. Field names follow Baidu Qianfan's beta video API. tokencoup does not rewrite the body and never persists the prompt. The response usage block (duration/resolution/total_tokens) is recorded as metadata only — total_tokens here is a video token count and is never summed into the token ledger.",
        "properties": {
          "model": {
            "type": "string",
            "description": "Video model ID from the Qianfan console (for example the fireseries / m-series models)."
          },
          "prompt": {
            "type": "string",
            "example": "a cat surfing a wave, cinematic"
          },
          "duration": {
            "type": "integer",
            "example": 5
          },
          "resolution": {
            "type": "string",
            "example": "720p"
          },
          "aspect_ratio": {
            "type": "string",
            "example": "16:9"
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "INTL / Mode A"
    },
    {
      "name": "INTL / Mode B"
    },
    {
      "name": "CN / Mode A"
    },
    {
      "name": "VIDEO / Baidu VOD v3"
    },
    {
      "name": "VIDEO / Qianfan native"
    }
  ]
}
