From ab564f84469cbc0b271bcffe575a28d9fdd92d58 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Mon, 6 Apr 2026 16:15:42 +0100 Subject: [PATCH] docs: add async task lifecycle to video and music generation --- docs/tools/music-generation.md | 19 +++++++++++++++++++ docs/tools/video-generation.md | 19 +++++++++++++++++++ 2 files changed, 38 insertions(+) diff --git a/docs/tools/music-generation.md b/docs/tools/music-generation.md index 7452521491b..de390ecb520 100644 --- a/docs/tools/music-generation.md +++ b/docs/tools/music-generation.md @@ -144,6 +144,25 @@ ignored with a warning when the selected provider or model cannot honor them. - Prompt hint: later user/manual turns in the same session get a small runtime hint when a music task is already in flight so the model does not blindly call `music_generate` again. - No-session fallback: direct/local contexts without a real agent session still run inline and return the final audio result in the same turn. +### Task lifecycle + +Each `music_generate` request moves through four states: + +1. **queued** -- task created, waiting for the provider to accept it. +2. **running** -- provider is processing (typically 30 seconds to 3 minutes depending on provider and duration). +3. **succeeded** -- track ready; the agent wakes and posts it to the conversation. +4. **failed** -- provider error or timeout; the agent wakes with error details. + +Check status from the CLI: + +```bash +openclaw tasks list +openclaw tasks show +openclaw tasks cancel +``` + +Duplicate prevention: if a music task is already `queued` or `running` for the current session, `music_generate` returns the existing task status instead of starting a new one. Use `action: "status"` to check explicitly without triggering a new generation. + ## Configuration ### Model selection diff --git a/docs/tools/video-generation.md b/docs/tools/video-generation.md index 82cac135bc1..268ec4b2133 100644 --- a/docs/tools/video-generation.md +++ b/docs/tools/video-generation.md @@ -57,6 +57,25 @@ While a job is in flight, duplicate `video_generate` calls in the same session r Outside of session-backed agent runs (for example, direct tool invocations), the tool falls back to inline generation and returns the final media path in the same turn. +### Task lifecycle + +Each `video_generate` request moves through four states: + +1. **queued** -- task created, waiting for the provider to accept it. +2. **running** -- provider is processing (typically 30 seconds to 5 minutes depending on provider and resolution). +3. **succeeded** -- video ready; the agent wakes and posts it to the conversation. +4. **failed** -- provider error or timeout; the agent wakes with error details. + +Check status from the CLI: + +```bash +openclaw tasks list +openclaw tasks show +openclaw tasks cancel +``` + +Duplicate prevention: if a video task is already `queued` or `running` for the current session, `video_generate` returns the existing task status instead of starting a new one. Use `action: "status"` to check explicitly without triggering a new generation. + ## Supported providers | Provider | Default model | Text | Image ref | Video ref | API key |