seedance-2-prompt — Seedance 2.0 video clip generator (dual backend)

Submits a Seedance 2.0 generation job and downloads the resulting MP4. Two backends share one CLI, picked via with.provider:

Both flavours follow submit-then-poll, but differ in request shape (OpenRouter uses a flat prompt field; ARK packs everything into a content[] array), polling URL (OpenRouter returns polling_url; ARK gets id and you construct /contents/generations/tasks/{id}), the terminal-success status (completed vs succeeded), and where the final MP4 URL sits (top-level unsigned_urls[0] vs content.video_url). This script normalises both into a single Python contract.

Inputs (with:)

input_image vs input_reference — input_image becomes the literal first frame. input_reference is a softer style + identity hint the model uses without locking the frame. For multi-shot drama, pass the same input_reference to every shot; pass input_image only when you want a specific opening frame.

Prompt rules (from upstream + OpenSquilla tightening)

1. One major action per 3-5s segment. Don't pack multiple motions.
2. Identity continuity — repeat the main character's full description in every shot's prompt.
3. Specific over poetic — "a young woman in a red trench coat walks through rain-soaked neon streets" >> "a woman walking".
4. Negative constraints inline — append no watermark, no logo, no subtitles, no on-screen text.
5. IP-safe — invent original character/brand names.
6. Aspect ratio explicit — append aspect_ratio: 9:16.

See references/recipes.md, references/modes-and-recipes.md, references/camera-and-styles.md for the upstream playbook.

Auth

• openrouter provider API-key resolution order:
  1. --api-key CLI argument
  2. OPENROUTER_API_KEY env var
  3. OPENSQUILLA_LLM_API_KEY env var, only when the effective OpenSquilla LLM provider resolves to openrouter
  4. llm.api_key or llm.api_key_env from the selected OpenSquilla TOML config. Config discovery matches GatewayConfig.load: explicit OPENSQUILLA_GATEWAY_CONFIG_PATH first; otherwise ./opensquilla.toml, then default_opensquilla_home()/config.toml. OPENSQUILLA_STATE_DIR changes default_opensquilla_home(), so a state-dir profile does not fall through to ~/.opensquilla. Config-file credentials are consumed only when the selected config's llm.provider is openrouter or omitted.
• volcengine / byteplus provider reads ARK_API_KEY (with provider- specific fallbacks VOLC_ARK_API_KEY / BYTEPLUS_API_KEY). No config-file fallback for these — the OpenSquilla [llm] config describes the agent's selected LLM provider, not ARK / BytePlus video credentials.
• All three send the key as Authorization: Bearer <key>.
• For OpenRouter the same bearer is also added when downloading the resulting unsigned_urls[0]. Volcengine returns pre-signed object store URLs that reject extra headers, so the downloader strips Authorization for non-OpenRouter hosts.

Output

Prints the absolute path of the saved .mp4 on stdout. Non-zero exit on any error; stderr carries the diagnostic.

Cost / latency

• OpenRouter bytedance/seedance-2.0 5s @ 9:16 720p: ≈30-90s wall, ≈$0.76.
• Volcengine official 5s 1080p: ≈30-120s wall, ≈$0.93.
• Volcengine doubao-seedance-2-0-fast-260128: roughly half cost and faster.
• The returned unsigned_urls / content.video_url expire 24 hours after success on the Volcengine path — this script downloads them before that window so the local mp4 is durable.

Multi-segment workflows (>15s)

Generate segments individually with duration ≤ 15, ending each on a stable hand-off frame. Stitch with the video-merger skill. See references/modes-and-recipes.md § "Multi-Segment Stitching".