docs(video): Seedance reference media on the x402 gateways, priced per reference second

docs/api-reference/video-generation.md

@@ -84,7 +84,7 @@ Notes:
 
 - **Sora 2** accepts only `duration_seconds` of **4, 8, or 12** — any other value returns `400` listing the allowed set. Text-to-video and image-to-video (`image_url`, non-human subjects only — see below). Output is 720p with synchronized audio, portrait or landscape; `resolution` and the Seedance-only params are ignored.
 - **Grok Imagine** accepts `duration_seconds` from **1 to 15** (default 8) and an optional `image_url` (first frame). `resolution` **is honored and is a billing tier** — `xai/grok-imagine-video` renders `480p`/`720p`, and `xai/grok-imagine-video-1.5` adds `1080p`; omitting it bills and renders `480p`, and anything off-tier returns a `400` before payment that lists the supported tiers and their rates. `aspect_ratio` is also honored: both SKUs accept `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `3:2`, `2:3` (the Seedance-only `adaptive` and `21:9` return a `400`). Grok Imagine Video **1.5** is xAI's flagship generation — better physics and prompt adherence, with native synced audio in the same pass. The remaining Seedance-only params (`generate_audio`, `seed`, RealFace, reference media) are not sent upstream for either Grok SKU.
-- **Seedance** supports a default of 5s, a floor of **4s** (a `duration_seconds` below 4 returns `400` before payment) and a per-tier maximum — **`seedance-2.5` allows up to 30s, `seedance-2.0` / `seedance-2.0-fast` / `seedance-2.0-mini` up to 15s, `seedance-1.5-pro` up to 12s** (above the max also returns `400`). The gateway bumps the default to **720p** and sets `generate_audio` per the t2v/i2v split below. `seedance-2.0`, `seedance-2.0-fast` and `seedance-2.0-mini` accept a `real_face_asset_id` (`ta_xxxx`) for character/identity consistency and multiple reference images (omni). `seedance-2.5` is text-to-video and image-to-video only: no RealFace, no first/last-frame, no reference media. `seedance-2.0-fast` finishes in ~60–80s; `seedance-2.0` (Pro) is higher quality and slower; `seedance-2.0-mini` is the budget tier at roughly half the Fast rate.
+- **Seedance** supports a default of 5s, a floor of **4s** (a `duration_seconds` below 4 returns `400` before payment) and a per-tier maximum — **`seedance-2.5` allows up to 30s, `seedance-2.0` / `seedance-2.0-fast` / `seedance-2.0-mini` up to 15s, `seedance-1.5-pro` up to 12s** (above the max also returns `400`). The gateway bumps the default to **720p** and sets `generate_audio` per the t2v/i2v split below. `seedance-2.0`, `seedance-2.0-fast` and `seedance-2.0-mini` accept a `real_face_asset_id` (`ta_xxxx`) for character/identity consistency and multiple reference images (omni). `seedance-2.5` takes first/last-frame seeding, up to **30** reference images and reference video/audio clips, but not RealFace. `seedance-2.0-fast` finishes in ~60–80s; `seedance-2.0` (Pro) is higher quality and slower; `seedance-2.0-mini` is the budget tier at roughly half the Fast rate.
 
 ---
 
@@ -115,9 +115,9 @@ An inline `data:` image is decoded and checked for real image bytes (PNG, JPEG,
 | `image_url` | string (URL or data URI) | No | Seed image for image-to-video (all video models support it). For `azure/sora-2` the image is resized server-side to Sora's exact dimensions and must not contain a human face. Mutually exclusive with `real_face_asset_id`. |
 | `real_face_asset_id` | string | No | Character/face reference asset (`ta_xxxxxx`) from a [Virtual Portrait](virtual-portrait.md) (AI character) or [RealFace](realface.md) (real person). **Seedance 2.0 / 2.0-fast / 2.0-mini only.** Mutually exclusive with `image_url`. |
 | `last_frame_url` | string (URL or data URI) | No | Final-frame target for first-and-last-frame interpolation. Send with `image_url` (first frame) — alone it returns `400`. **Seedance only** (1.5-pro, 2.0-mini, 2.0-fast, 2.0). Cannot be combined with `real_face_asset_id`. |
-| `reference_image_urls` | string[] (1–9) | No | Multiple reference images for character/style consistency (cite them as "image 1", "image 2" in the prompt). **`seedance-2.0` / `seedance-2.0-fast` / `seedance-2.0-mini` only.** Its own mode — cannot be combined with `image_url`, `last_frame_url` or `real_face_asset_id`. No surcharge. |
-| `reference_videos` | array of `{url, role?}` (1–3) | No | Reference videos for reference-to-video (r2v). **Live** on `bytedance/seedance-2.0`, `bytedance/seedance-2.0-fast` and `bytedance/seedance-2.0-mini`; any other model is a `400` before payment. `url` must be `http(s)` and ≤ 2048 characters. `role`, if sent, must be `"reference"` — it is the only role the upstream honours. Each reference video multiplies the token quote by 1 (so one clip doubles it); see the surcharge note below. Flat `video_url` is rejected with a `400` pointing at this field. |
-| `reference_audios` | array of `{url, role?}` (1–3, each ≤15.2s) | No | Reference audios for r2v, same models and same `url` / `role` rules as `reference_videos`. Each reference audio adds 0.3 to the token multiplier. Flat `audio_url` is rejected with a `400` pointing at this field. |
+| `reference_image_urls` | string[] (1–9; 1–30 on `seedance-2.5`) | No | Multiple reference images for character/style consistency (cite them as "image 1", "image 2" in the prompt). **`seedance-2.0` / `seedance-2.0-fast` / `seedance-2.0-mini` / `seedance-2.5` only.** Its own mode — cannot be combined with `image_url`, `last_frame_url` or `real_face_asset_id`. No surcharge. |
+| `reference_videos` | array of `{url, role?, duration_seconds?}` (1–3) | No | Reference videos for reference-to-video (r2v). **Live** on `bytedance/seedance-2.0`, `bytedance/seedance-2.0-fast`, `bytedance/seedance-2.0-mini` and `bytedance/seedance-2.5`; any other model is a `400` before payment. Each clip must be within the model's ceiling: **15.2s** on the 2.0 family, **30.2s** on 2.5. `url` must be `http(s)` and ≤ 2048 characters. `role`, if sent, must be `"reference"` — it is the only role the upstream honours. `duration_seconds` is optional and is **not** used for pricing; a declared length over the model's ceiling gets a `400` before payment. Billed per reference second; see the reference-media note below. Flat `video_url` is rejected with a `400` pointing at this field. |
+| `reference_audios` | array of `{url, role?, duration_seconds?}` (1–3) | No | Reference audios for r2v, same models, ceilings and `url` / `role` / `duration_seconds` rules as `reference_videos`. Needs a reference image or video alongside. A reference audio second is billed at 0.3× a reference video second. Flat `audio_url` is rejected with a `400` pointing at this field. |
 | `input_type` | string | No | Optional validated enum: `text` / `image` / `first_last_frame` / `reference`. When supplied it must match the seed fields you actually sent or the request returns a `400` carrying `inferred_input_type`. |
 | `duration_seconds` | integer | No | Duration to bill for. Defaults to the model default. Must respect the model's range (Seedance: 4s floor; 2.5 = 30s, 2.0 / 2.0-fast / 2.0-mini = 15s, 1.5-pro = 12s max; Grok: 1–15; Sora 2: the discrete `{4,8,12}` set) or you get a `400` before payment. |
 | `resolution` | string | No | `480p` / `720p` / `1080p` / `4K`, gated **per model** from the upstream parameter schema: `bytedance/seedance-2.0` accepts all four (`4K` is real 3840×2160); `seedance-1.5-pro` accepts `480p` / `720p` / `1080p`; `seedance-2.0-fast` and `seedance-2.5` accept `480p` / `720p` only. **Defaults to `720p`** on Seedance; higher resolutions cost more tokens upstream. Anything off-list returns a `400` before payment (`360p` / `540p` / `1K` / `2K` are not offered by any model). `seedance-2.0-mini` renders `480p` / `720p` — keep to those; a higher value is not rejected up front for this SKU. On Grok it selects the billing tier (see above); Sora ignores it. |
@@ -164,6 +164,8 @@ All prices below are the amounts quoted in the `402` challenge and actually bill
 
 **Seedance token math:** at the 720p default a clip uses **~21,690 tokens/second** (a 5s clip ≈ 108,450 tokens). Price = `duration × 21,690 × resolution-factor × rate-per-M ÷ 1,000,000 × 1.05 + $0.001`. Image-to-video is billed at the **same per-token rate** as text-to-video (no i2v discount). The resolution token factor relative to 720p (=1) is: `480p ×0.5`, `1080p ×2.25`, and `4K ×9` (area-proportional) — so dropping to `480p` halves the per-clip cost and `1080p`/`4K` cost proportionally more (a 5s `seedance-2.0` clip is ≈ $2.556 at 1080p and ≈ $10.220 at 4K). `4K` (real 3840×2160) is available **only on `bytedance/seedance-2.0`**; the ceiling is `1080p` on `seedance-1.5-pro` and `720p` on `seedance-2.0-fast`/`seedance-2.0-mini`/`seedance-2.5`; anything above a model's ceiling returns a `400` before payment. On a completed poll the response carries `usage.total_tokens` with `token_source: "upstream"` when the upstream reported the metered count, or `"estimated"` when the gateway fell back to this formula. Sora ignores resolution. Grok Imagine bills per second **by resolution tier**, at xAI's official rates with no margin: on `xai/grok-imagine-video` `480p` is $0.05/sec (the default when `resolution` is omitted) and `720p` $0.07/sec, with `1080p`/`4K` rejected before payment; on `xai/grok-imagine-video-1.5` `480p` is $0.08/sec (default), `720p` $0.14/sec and `1080p` $0.25/sec, with `4K` rejected before payment. Both SKUs add a flat **$0.001 per generation** on top of rate × duration — it does not scale with length, so a 1s clip and a 15s clip carry the same one.
 
+**Reference media:** a reference video second costs about what an output second costs (~21,600 tokens/second, measured). The gateway cannot read a clip's length before it is fetched, so **every reference clip is quoted at its model's ceiling**, rounded down to whole seconds as the upstream bills: 15s on the 2.0 family and 30s on `seedance-2.5`. A declared `duration_seconds` never lowers the quote. Reference images add nothing. At 720p, one reference video on a 5s clip quotes **$4.529** on `seedance-2.0`, **$1.590** on `seedance-2.0-mini` and **$11.007** on `seedance-2.5`. The 402 and 202 bodies carry a `quote_basis` block saying exactly this (`reference_duration_selection: "per_clip_model_ceiling"`, `media_duration_verified: false`), and the poll settles that same amount.
+
 **One-time enrollment fees (separate from per-call billing):**
 
 | Action | Endpoint | Price |