A multi-step content task runs in the background while you keep chatting
spawn_background_task is several tools in one async job. Treating a single generate as a pipeline wastes credits.
A multi-step content task runs in the background while you keep chatting. Kick it off. Keep chatting while it runs. spawn_background_task is for jobs that take more than about thirty seconds and combine several generations: movie-plus-music, slideshow-to-reel, bulk generate, generate-then-post. It can start now or at scheduled_at. Using it for one still, or blocking the thread on a five-step pipeline you refused to background, wastes credits on retries you launched because you thought the chat had died.
Automate a multi-step content task is the named capability. You describe the steps. The agent runs them asynchronously with real-time progress. Every task also saves itself as a reusable workflow keyed on task_name. Pick a clean name (Instagram Vlog with Captions), not Vlog Rerun v2.
What this job actually is
The unit is a pipeline, not a clip. "Generate 5 product images, turn them into a slideshow, and post it to Instagram — run this in the background." Priced as the sum of each step's generation, shown as the task plans out. Optional future start time. You do not stare at a spinner. You can still ask other questions in the same conversation.
Re-run later by listing saved workflows, reading the stored brief, and spawning a new task that respects that brief. That is the point of auto-saving. A background task you never name is a pipeline you will re-explain next month.
What wastes credits
One generate, wrapped in ceremony. A square product still does not need spawn_background_task. Call the image job. Backgrounding a single cheap generate adds a workflow object and a status card for no gain.
A movie or a template you already have a specialist for. Create a multi-scene AI movie is the film. Run a one-tap AI video template is the template. Set up a full content pipeline plans from a high-level brief. This job is the async runner for a step list you can name. Sending "make an ad" here without steps is how you get a narrated pipeline you did not want.
Closing the tab as cancel. A background task is server-side. It does not die with the socket. If you wanted it stopped, say so. Walking away mid-plan and spawning it again is a double spend.
Irreversible posts inside an unreviewed plan. Several tools plus a publish belong in Plan first. A background task that posts on step four will post. Approve the steps if a step is a publish.
The test
Will this take more than one tool, and longer than a single generate, and do you want to keep chatting?
If yes, this is the job. Name the task. List the steps. Background it.
If it is one clip, generate. If it is a saved scene recipe, run the workflow. If it is a recurring series, schedule that series. This is one named agent job. Using it for a different job wastes credits.
FAQ
Does every run create a saved workflow?
Yes. That is why task_name should be intent-based and stable. A unique name per retry is how your workflow list becomes a junk drawer.
Can I start it tomorrow morning instead of now?
Yes. scheduled_at is a first-class field. "Run this tomorrow at 8am" is this job, not a calendar app.
Is this the same as a recurring video series?
No. Run a recurring video series turns a saved video workflow into a cadence with a fresh plot each tick. This job is an async step list, including one-off bulk work. Recurring series is the clock. Background task is the runner.
What if a step gets stuck?
Do not spawn a second copy of the whole pipeline. Check the run. Check or resume a stuck workflow run is the recovery job. A duplicate spawn is how you pay twice for scene one.