docs(skill): token-billed image models

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

references/billing.md

@@ -27,5 +27,20 @@ a call cost. The main Skill is <https://beatapi.io/skill.md>.
 - 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: <https://beatapi.io/pricing>.
+- 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): <https://beatapi.io/skill-refs/errors.md>.
 Connecting a host: <https://beatapi.io/skill-refs/setup.md>.

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:
+  <https://beatapi.io/skill-refs/billing.md>.
 - **Text models** run the same way: `{"reference":"model:<id>","input":{"input":"<prompt>"}}`
   returns `output_text`; `usage` token counts may include upstream system prompts
   and are not comparable across models. **Decision model** JEV:

skills/beatapi-video/references/billing.md

@@ -27,5 +27,20 @@ a call cost. The main Skill is <https://beatapi.io/skill.md>.
 - 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: <https://beatapi.io/pricing>.
+- 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): <https://beatapi.io/skill-refs/errors.md>.
 Connecting a host: <https://beatapi.io/skill-refs/setup.md>.

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:
+  <https://beatapi.io/skill-refs/billing.md>.
 - **Text models** run the same way: `{"reference":"model:<id>","input":{"input":"<prompt>"}}`
   returns `output_text`; `usage` token counts may include upstream system prompts
   and are not comparable across models. **Decision model** JEV:

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', () => {