| name | generation |
| description | Use when the user asks to generate images / videos / clips, or when an existing async task needs tracking. Triggers on "generate", "create an image", "make a video", "render", "what's the status of X task", "wait for it to finish". Use the `clash tasks` CLI subcommands. |
Generation tasks
Generation in Clash (image, video, clip edits) runs as background tasks.
You don't kick them off with clash tasks; you trigger them by
executing an action node on the canvas (see canvas-operations skill,
clash canvas execute). The tasks subcommand exists to track them
afterwards.
The shape of a generation node
A generation action-badge node carries four inputs — regardless of
whether it produces an image, video, audio, or text:
| field | what it holds |
|---|
prompt | the text instructions |
model | the provider model id (gemini-flash-image, veo3-fast, …) |
modelParams | model-specific knobs (aspectRatio, duration, seed, …) |
references | a list of canvas asset ids the model should consume as input |
You don't tell the system what mode you're in (img2img vs text2img,
v2v vs t2v, etc.). You just attach the references you want and the
system partitions them into referenceImageAssetIds,
referenceVideoAssetIds, referenceAudioAssetIds by each asset's kind.
The model card decides which subset it can actually use (text-only
models will reject image refs at validation time, etc.).
References can be supplied two ways, and they compose:
- Inline in the prompt —
"make a poster of @[Penguin](node:abc) on the moon" —
the CLI extracts the @-mentions, resolves each <id> to its asset.
This is the natural way when the reference is contextually part of the
prompt text.
- Via
--ref — --ref <node-or-asset-id>, repeatable — when you
want the reference in but don't want it in the prompt text.
Typical sequence
- User: "generate a 5-second clip of a sunrise"
- You: ensure the right action node exists on the canvas (or create one
via canvas-operations using
--prompt … --model … --ref … --param k=v),
get its id, then:
clash canvas execute <action-node-id> --json
This returns a task id.
- Wait for the task:
clash tasks wait <task-id> --timeout 300 --json
--timeout is in seconds; default 120 is too short for video. Use
300 for image gen, 600+ for video. The command blocks until the task
reaches a terminal state then prints the final status (with the asset
id when it succeeded).
- Surface the result. The user can see the new asset on the canvas —
you don't need to embed it. One sentence is enough: "done — sunrise
clip is on the canvas".
Polling without blocking
clash tasks status <task-id> --json
Returns current state without waiting. Useful if the user wants a quick
"is X done yet" check. Don't loop this in a tight poll — use wait
instead.
On failure
tasks wait exits non-zero if the task ends in failed (or times out).
Read the JSON's error field and surface it concisely. Common failures:
- model out of credits → suggest the user check billing
- prompt rejected by safety filter → suggest a rewording
- network / upstream error → safe to retry once
Conventions
- Show the task id you're waiting on in your progress message — the
user might want to check it themselves on a different device.
- For batch ops (generate 4 variants), kick all four off with
execute,
then wait on each one in turn (sequential is fine; the user mostly
cares about the last one finishing). Don't fan out parallel waits.
