seedance-2-prompt

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:

| with.provider | Endpoint | Auth env | Default model |

|---|---|---|---|

| openrouter (default) | https://openrouter.ai/api/v1/videos | OPENROUTER_API_KEY | bytedance/seedance-2.0 |

| volcengine (CN) | https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks | ARK_API_KEY (or VOLC_ARK_API_KEY) | doubao-seedance-2-0-260128 |

| byteplus (intl) | https://ark.ap-southeast.bytepluses.com/api/v3/contents/generations/tasks | ARK_API_KEY (or BYTEPLUS_API_KEY) | dreamina-seedance-2-0-260128 |

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:)

| key | required | default | notes |

|---|---|---|---|

| prompt | yes | — | Structured English video prompt (use this skill's recipes). |

| filename | yes | — | Output .mp4 path. |

| provider | no | openrouter | openrouter, volcengine, or byteplus. |

| aspect_ratio | no | 9:16 | 9:16, 16:9, 1:1, 4:3, 3:4, 21:9. |

| duration | no | 5 | Seconds, 3-15. OpenRouter Seedance accepts 4-15; a 3-second request generates a real 4-second provider clip and is trimmed locally to exactly 3 seconds. |

| resolution | no | 720p | 480p, 720p, 1080p. Ignored by OpenRouter. |

| model | no | provider default | Override model id. Empty means use provider default. |

| input_image | no | "" | Strict first-frame path. If set, video starts from this image. |

| input_reference | no | "" | Primary soft identity/style anchor path. Used only when input_image is empty. Same anchor passed across shots locks the character. |

| input_reference_2 | no | "" | Optional second reference (e.g. per-shot scene composition). Forwarded as a second --input-reference so the underlying provider sees both. Empty strings are filtered out before the API call. |

| max_retries | no | 0 | Extra retries for transient polling HTTP 429/5xx or transport failures after a job id is issued, capped at 5; every retry stays on that same job. A paid POST submit is never retried automatically, including an ambiguous 429/5xx or transport failure, because the provider may already have accepted and billed it. HTTP 401/403/other 4xx, terminal policy failures, and invalid downloaded media also stop immediately. 0 = no extra polling retry. |

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.

1. Specific over poetic — `"a young woman in a red trench coat

walks through rain-soaked neon streets" >> "a woman walking"`.

1. Negative constraints inline — append `no watermark, no logo,

no subtitles, no on-screen text.`

1. IP-safe — invent original character/brand names.
2. 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. The parent-injected atomic tuple

OPENSQUILLA_META_CAPABILITY_PROVIDER,

OPENSQUILLA_META_CAPABILITY_API_KEY, and

OPENSQUILLA_META_CAPABILITY_BASE_URL; optional

OPENSQUILLA_META_CAPABILITY_PROXY is used only for the matching

provider's authenticated API requests

1. OPENSQUILLA_META_OPENROUTER_API_KEY, retained for older parent runtimes

and bound to OpenRouter's official origin

1. OPENROUTER_API_KEY for direct CLI use, also bound to the official origin

• The generic parent key is accepted only with its matching provider and base

URL. Parent and canonical environment credentials allow same-origin path

changes through --base-url, but never a scheme, hostname, or effective-port

change. Direct CLI users who intentionally select a different origin must

pass both --api-key and --base-url.

• The child never discovers or parses opensquilla.toml from its workspace

and never honors a workspace-selected arbitrary llm.api_key_env. Configure

the active Gateway normally; its parent runtime performs that resolution.

• When a parent-resolved profile-pool credential receives an authentication,

credit, or rate-limit failure, OpenSquilla parks that key for the next

explicitly authorized run. It never repeats the current paid generation

automatically.

• 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> only to an API URL

whose scheme, hostname, and effective port exactly match the configured

provider base. Authenticated redirects are not followed. A provider-supplied

cross-origin polling URL is ignored in favour of the canonical job URL under

the trusted base. A parent-injected proxy is used for these matching provider

API requests only and never for anonymous media downloads.

• Media downloads are always anonymous, including URLs hosted by OpenRouter.

Download URLs and every redirect must use HTTPS, contain no userinfo, and

resolve exclusively to public addresses; localhost, private, loopback,

link-local, reserved, unspecified, and multicast targets are rejected. Each

connection is pinned to the address that passed validation while retaining

the original TLS SNI/hostname, eliminating DNS-rebinding between validation

and connection.

Output

Prints the absolute path of the saved .mp4, then a

VIDEO_GENERATION_RECEIPT: {...} line on stdout. A matching sanitized

receipt is saved as <filename>.receipt.json; it records provider,

model, safe job id, and ffprobe verification metadata for both the

provider clip and final clip. Downloads first land in a private

same-directory candidate file. The script requires a real video stream,

positive duration, reasonable dimensions, and duration within tolerance;

3-second requests are probed both before and after the local trim. Only a

verified candidate is atomically published with os.replace, so an HTML

error page, truncated download, or failed trim cannot overwrite an existing

output. The receipt never contains the API key, prompt, raw provider response,

request/generation metadata, usage payload, or signed download URL. Logs omit

URL queries/fragments and raw provider messages. Non-zero exit on any error;

stderr carries a sanitized status/code summary when available.

On a recognized provider-policy rejection, the script stops immediately and

persists a failure sidecar instead of fabricating API success. That sidecar is

strictly limited to status=policy_rejected, provider/model,

reason=provider_policy_rejected, and the allowlisted policy_code; it never

contains raw provider text, signed URLs, request/job IDs, prompts, or secrets.

Meta workflows can then run their local fallback while preserving an honest,

user-visible degraded reason for the delivery audit.

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".