feat(video): Seedance reference media and output controls, guarded per model and rail (supersedes #70)

[VickyXAI]

Supersedes #70 by @KillerQueen-Z. Their commit is cherry-picked onto current main with authorship kept. #70's branch carried 253 rewritten copies of main's commits and conflicted with main.

What #70 adds (kept)

• reference_videos and reference_audios on VideoClient.generate and SolanaLLMClient.video (sync and async).
• Up to 30 reference images on seedance-2.5.
• bitrate_mode, output_format, camera_fixed, safety_identifier.
• VideoClip.last_frame_url / last_frame_backed_up.

What review found, and the fixes

1. P0 (on main already; feat(video): expose Seedance reference media and output controls #70 routed reference users into it): Solana account rail bills, then crashes.
   • With a brk_ key, _request_image_with_payment's first POST is the billed submit. Its 202 {id, poll_url} stub was returned as the result, so VideoResponse raised after the charge, with no job id.
   • A 502/503 replayed the billed POST.
   • The job is now polled unsigned to completion. 5xx is not replayed. A timeout says the account was billed and carries poll_url.
   • Both sync and async are fixed. The new tests fail on main and pass here.
2. P1: reference media was advertised on every rail.
   • Both wallet gateways 400 every reference_* field before quoting (blockrun#728, blockrun-sol#374).
   • It is now refused locally with a pointer to BLOCKRUN_API_KEY.
3. P1: no per-model guards.
   • A shared validate_video_request (validation.py) mirrors the MCP's table in src/tools/video.ts. It replaces the two duplicated validator blocks.
   • It refuses clips on 2.5, reference images on 1.5-pro, Grok and Sora, and audio-only references.
   • It refuses output_format off 2.5, bitrate_mode off 2.x, camera_fixed off 1.5-pro, and seedance-2.5 last frame on the Solana wallet gateway (MCP 0.53.1 parity).
   • It refuses clip dicts with extra keys and non-http(s) reference images.
   • On the account rail there is no quote step, so this check is the only gate before a charge.
4. P1: reference-clip billing was not documented.
   • Each clip bills at the 15.2s reference ceiling (blockrun#730).
   • This is now documented on the kwargs and in docs/seedance-capabilities.md.
5. P2: the root SEEDANCE_CAPABILITIES.md described gateway and MCP internals and claimed parity the SDK does not have. It is replaced by an SDK-scoped doc. A CHANGELOG entry is added under Unreleased.

Behaviour change to note

reference_image_urls on a wallet client now raises ValueError locally. Before, the SDK forwarded it and the gateway refused it with a 400. Either way it did not work; it now fails before any request.

Verification

• pytest tests/unit: 1016 passed. Offline only, with an isolated HOME and mock transports.
• black --check . and ruff check . are clean.
• Nothing hits the gateway.

🤖 Generated with Claude Code