From 69b0a6dc542294099d4c446451049c6a6fa5ab21 Mon Sep 17 00:00:00 2001 From: li Date: Thu, 5 Nov 2026 17:09:14 +0800 Subject: [PATCH] docs(skill): token-billed image models The six -token image models (gpt-image-2-token, the GPT Image 2.5 Flare and Sunburst token pair, nano-banana-2/-pro/-2-lite-token) are their base models billed by the tokens each image uses. billing.md says how they are charged (credits_reserved is the estimate, credits_settled the tokens used), that the GPT ones take an optional quality and the fixed-price GPT models refuse it, and that they run as async tasks only, with no /v1/images/generations. run.md points there; both bundled copies match their sources. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 3 +++ references/billing.md | 15 +++++++++++++++ references/run.md | 2 ++ skills/beatapi-video/references/billing.md | 15 +++++++++++++++ skills/beatapi-video/references/run.md | 2 ++ test/setup-walkthrough.test.mjs | 3 +++ 6 files changed, 40 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0978733..4c241f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,9 @@ ### Added +- Token-billed image models (`-token` IDs): how they are charged (reserved estimate, + settled tokens), the GPT `quality` setting, and that they run as async tasks only, + in `billing.md`, with a pointer from `run.md`. - SEO research recipe for a domain, using the `data:seo.*` capabilities, linked from the index. ### Changed diff --git a/references/billing.md b/references/billing.md index 9b3f1db..91c8d6f 100644 --- a/references/billing.md +++ b/references/billing.md @@ -27,5 +27,20 @@ a call cost. The main Skill is . - Report cost from the response's `usage` (`price_usd`, sync calls) or the task's `credits_settled`; both are US dollars. +## Token-billed image models + +- An image model whose ID ends in `-token` (`gpt-image-2-token`, + `nano-banana-2-token`, …) is its base model billed by the tokens each image + uses, not a flat price per image. Same request fields as the base model. +- `credits_reserved` is the estimate held when the task is created; + `credits_settled` is the tokens the render actually used, so the two can + differ. A failed task is not charged. Rates per 1M tokens and per-image + estimates: . +- The GPT ones take an optional `quality` (Inspect lists the levels; default + `medium`) that sets the output tokens and so the price. Their fixed-price + GPT models refuse `quality`; the Nano Banana ones have no `quality`. +- Async only: run them like any image task and poll until `succeeded`. There is + no synchronous `/v1/images/generations` for them. + Balance too low (402) or a rejected key (401): . Connecting a host: . diff --git a/references/run.md b/references/run.md index 4a0d3f1..70f2264 100644 --- a/references/run.md +++ b/references/run.md @@ -47,6 +47,8 @@ Over MCP, pass the same JSON to `capabilities_run`. 45 s) before answering; an image or video task comes back at once. A music video can also stop at `requires_action` or `storyboard_ready`, which needs the user's choice. + `-token` image models are async only and billed by tokens: + . - **Text models** run the same way: `{"reference":"model:","input":{"input":""}}` returns `output_text`; `usage` token counts may include upstream system prompts and are not comparable across models. **Decision model** JEV: diff --git a/skills/beatapi-video/references/billing.md b/skills/beatapi-video/references/billing.md index 9b3f1db..91c8d6f 100644 --- a/skills/beatapi-video/references/billing.md +++ b/skills/beatapi-video/references/billing.md @@ -27,5 +27,20 @@ a call cost. The main Skill is . - Report cost from the response's `usage` (`price_usd`, sync calls) or the task's `credits_settled`; both are US dollars. +## Token-billed image models + +- An image model whose ID ends in `-token` (`gpt-image-2-token`, + `nano-banana-2-token`, …) is its base model billed by the tokens each image + uses, not a flat price per image. Same request fields as the base model. +- `credits_reserved` is the estimate held when the task is created; + `credits_settled` is the tokens the render actually used, so the two can + differ. A failed task is not charged. Rates per 1M tokens and per-image + estimates: . +- The GPT ones take an optional `quality` (Inspect lists the levels; default + `medium`) that sets the output tokens and so the price. Their fixed-price + GPT models refuse `quality`; the Nano Banana ones have no `quality`. +- Async only: run them like any image task and poll until `succeeded`. There is + no synchronous `/v1/images/generations` for them. + Balance too low (402) or a rejected key (401): . Connecting a host: . diff --git a/skills/beatapi-video/references/run.md b/skills/beatapi-video/references/run.md index 4a0d3f1..70f2264 100644 --- a/skills/beatapi-video/references/run.md +++ b/skills/beatapi-video/references/run.md @@ -47,6 +47,8 @@ Over MCP, pass the same JSON to `capabilities_run`. 45 s) before answering; an image or video task comes back at once. A music video can also stop at `requires_action` or `storyboard_ready`, which needs the user's choice. + `-token` image models are async only and billed by tokens: + . - **Text models** run the same way: `{"reference":"model:","input":{"input":""}}` returns `output_text`; `usage` token counts may include upstream system prompts and are not comparable across models. **Decision model** JEV: diff --git a/test/setup-walkthrough.test.mjs b/test/setup-walkthrough.test.mjs index 675a649..a6390f1 100644 --- a/test/setup-walkthrough.test.mjs +++ b/test/setup-walkthrough.test.mjs @@ -122,6 +122,9 @@ test('key handling is explicit about format and secrecy', () => { assert.match(billing, /Configure it privately/); assert.match(billing, /GET https:\/\/api\.beatapi\.io\/v1\/usage/); assert.match(billing, /Credits are US dollars everywhere/); + assert.match(billing, /ends in `-token`/); + assert.match(billing, /no synchronous `\/v1\/images\/generations`/); + assert.match(page('run'), /`-token` image models are async only/); }); test('errors branch on retryable and name the key failures', () => {