Source: https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/ # 🎨Creative-Agent Workflows `POST /v1/creative-agent/workflows` starts one durable creative workflow shape: an `input` object with explicit `steps`. Your application provides the exact steps and tool arguments up front. Use this endpoint when your application already knows the media operation to run and needs durable state, replayable event logs, SSE progress, resume, or cancellation. ## [#](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#workflow-endpoints)Workflow Endpoints | Endpoint | Method | Use | | --- | --- | --- | | `/v1/creative-agent/workflows` | `POST` | Start a durable creative-agent workflow. | | `/v1/creative-agent/workflows` | `GET` | List the caller's workflows. | | `/v1/creative-agent/workflows/:id` | `GET` | Read a workflow snapshot. | | `/v1/creative-agent/workflows/:id/events` | `GET` | Read the persisted event log. | | `/v1/creative-agent/workflows/:id/events/stream` | `GET` | Stream workflow events over SSE. | | `/v1/creative-agent/workflows/:id/resume` | `POST` | Resume a recoverable workflow from persisted step state. | | `/v1/creative-agent/workflows/:id/confirm-cost` | `POST` | Approve or reject the cost preview for a workflow paused with `cost_approval_required`. | | `/v1/creative-agent/workflows/:id/cancel` | `POST` | Cooperatively cancel a workflow. | | `/v1/creative-agent/workflows/:id/reseed` | `POST` | Clone a completed or partial-failure workflow with fresh seeds. | All workflow routes require authentication. Starting a workflow requires API-key auth. The `POST` response returns after validation, plan creation, and initial persistence. Treat the `201` response as acceptance plus the first workflow snapshot, not as completion. Use the workflow snapshot, event log, or SSE stream to observe progress until the status becomes terminal. Workflow status values are `queued`, `running`, `completed`, `partial_failure`, `waiting_for_user`, `failed`, and `cancelled`. SSE streams close on the terminal statuses β€” `completed`, `failed`, `partial_failure`, or `cancelled`. A `waiting_for_user` pause (including a cost-approval pause) keeps the stream open and resumes on the same connection after the pause is resolved. A `partial_failure` can still include artifacts from earlier completed steps. A `waiting_for_user` snapshot also carries a `waitingReason` naming why the run paused: `ask_clarifying_question`, `select_media_required`, `cost_approval_required`, `cost_reauthorization_required`, `safety_review_required`, `workflow_user_input_required`, `insufficient_credit`, `permission_required`, or `other`. Only the two cost reasons are resolved through [`POST /:id/confirm-cost`](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#confirm-cost); those snapshots also set `awaitingCostApproval: true`, which is the field to branch on rather than matching reason strings. Both fields are derived per response, so older workflow records return them too. ## [#](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#start-request)Start Request Request fields use snake\_case (shown below). Unknown field names β€” including camelCase variants β€” are rejected with a `400`. | Field or Header | Use | | --- | --- | | `input` | Required durable workflow input: `{ "title": "...", "steps": [...] }`. | | `input.steps` | Required array of exact creative-agent tool steps. | | `workflow_id` | Alternative to `input.steps`. Compile and run a saved workflow template by ID. | | `inputs` | Input values for a `workflow_id` template run. | | `Idempotency-Key`, `X-Idempotency-Key` | Optional retry key. Reusing the same key returns the existing workflow instead of launching duplicate media jobs. | | `max_estimated_capacity_units` | Optional ceiling. Rejects the workflow before persistence if the shared estimate is above this value. | | `confirm_cost` | Optional explicit cost confirmation. Set `false` to reject positive estimated-cost workflows until your caller retries with confirmation. | | `token_type` | Optional. Which token pays when tokens are billed: `spark`, `sogni`, or `auto` (default). External media providers still settle in Spark. | | `billing_mode` | Optional. Whether an active Unlimited plan or your token balance pays: `auto` (default), `subscription`, or `tokens`. See [Plan or tokens](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#plan-or-tokens). | | `app_source` | Optional caller identifier for analytics and support. | | `safe_content_filter` | Optional Sensitive Content Filter state for this workflow. Defaults to `true`. Send `false` to generate mature-theme work on models that allow it. | | `media_references` | Optional request-level media references available to workflow steps and `$input_media` dependency bindings. | ### [#](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#sensitive-content-filter)Sensitive Content Filter The filter is a **per-request** setting on the API and defaults to on. The [Sensitive Content Filter](https://docs.sogni.ai/sogni-create/studio/advanced/safe-content-filter/) switch in Sogni Web and Sogni Chat is stored in that browser and does **not** carry over to API calls β€” send `safe_content_filter: false` on each request instead. Turning it off needs an eligible account β€” an active Sogni subscription, Premium Spark, or paying with SOGNI. Sogni re-checks eligibility on every render, so an ineligible account is refused at generation time even when the flag is set. Some models keep their own content policies that the flag cannot override: the GPT Image 2 and GPT Image 2.5 models, and the Seedance 2.x, HappyHorse, and standard Wan 3 video models, refuse mature-theme prompts either way. Child-safety prompt screening is a separate system with its own rules, and this flag does not control it. A workflow started with the filter on rejects a mature-theme step with `SAFETY_REJECTED` and pauses on `waiting_for_user` with `waitingReason: "safety_review_required"`. Resume it with the filter off rather than rebuilding the workflow β€” see [Resume A Workflow](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#resume-a-workflow). ### [#](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#plan-or-tokens)Plan or tokens Two fields decide how a workflow is paid, and they control different things: - `token_type` picks **which token** pays when tokens are billed: Spark or SOGNI. - `billing_mode` picks **whether an active [Unlimited plan](https://docs.sogni.ai/pricing/unlimited-plan-details/) or your token balance** pays. | `billing_mode` | Behavior | | --- | --- | | `"auto"` | Default. An active Unlimited plan covers every step it can, and no tokens are spent on those steps. Everything else bills your token balance according to `token_type`. Without a plan, this is plain token billing. | | `"subscription"` | Bill eligible steps against your Unlimited plan only. A step the plan cannot cover fails instead of billing tokens. | | `"tokens"` | Always bill your token balance according to `token_type`, even when a plan is active. | Any other value returns `400`. External vendor models are never plan-covered and always bill Premium Spark, whatever `billing_mode` says. A plan does not cover a request that asks to pay in SOGNI (`token_type: "sogni"`): under `auto` that request is paid in SOGNI. Changing `token_type` does not move a job off your plan: with an active plan and `billing_mode` left at `auto`, eligible steps are plan-covered whether `token_type` is `spark` or `auto`. To spend Premium Spark you hold while a plan is active, send `billing_mode: "tokens"`. Jobs paid with Premium Spark get fastest-priority queue access, ahead of plan-covered jobs. ``` { "input": { "title": "Priority render", "steps": [ { "...": "..." } ] }, "token_type": "spark", "billing_mode": "tokens" } ``` [Resume](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#resume-a-workflow) and [reseed](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#reseed-a-workflow) accept `billing_mode` too. A reseed inherits the source run's setting unless you send a new one. On resume, a new value replaces the stored one for the rest of the run. ### [#](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#limits-errors-and-retries)Limits, errors, and retries The API limits how many workflows one account can have active at once (10 by default) and how fast it can start new ones (300 per hour by default), and it caps active workflows platform-wide. A start or reseed that runs into one of these is refused before anything is billed: | Status | Meaning | What to do | | --- | --- | --- | | `409` | You already have the maximum number of active workflows. `details.activeWorkflowCount` and `details.activeWorkflowLimit` give the numbers. | Wait for one of your workflows to finish, or cancel one, then send the start again. Follow a running workflow with [`/stream`](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#stream-events) or `GET /:id` rather than re-sending the start. This refusal does not use up your start allowance. | | `429` | You are starting workflows too fast, or the platform is at capacity. A start-rate refusal carries the wait in the `Retry-After` header and, in seconds, in the body's `retryAfter`. | Wait at least that long before the next start; a request sent sooner is refused again. When no wait is given, back off with jitter before retrying. | ``` { "status": "error", "errorCode": 126, "message": "Creative workflow start rate limit exceeded. Wait before starting another workflow.", "retryAfter": 1837, "details": { "retryAfterSeconds": 1837 } } ``` Send an `Idempotency-Key` on every start and reseed, and reuse it when you retry a request that timed out or lost its connection. The retry returns the workflow the first request created instead of starting, and billing, another one. A workflow can carry many steps, so batching related renders into one workflow uses one active slot for all of them. For render concurrency, serverless patterns, and billing for production volume, see [Production Integrations](https://docs.sogni.ai/api-reference/production-integrations/). Need higher limits? Tell us what you're building at [hello@sogni.ai](mailto:hello@sogni.ai). ## [#](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#step-shape)Step Shape A workflow supports at most **12 steps** per run. Each step supplies an exact hosted tool call: ``` { "id": "clip", "toolName": "animate_photo", "arguments": { "prompt": "Slow dolly-in on the generated keyframe.", "videoModel": "ltx25", "duration": 5 }, "dependsOn": [ { "sourceStepId": "keyframe", "sourceArtifactIndex": 0, "targetArgument": "sourceImageIndex", "mediaType": "image", "transform": "image_index", "required": true } ] } ``` Steps submitted through `input.steps` run one at a time, in array order. `dependsOn` wires an earlier step's artifact into a later step's arguments; it does not reorder execution, so list the steps in the order they should run. Concurrency exists only for template runs: a `BatchStage` compiles to sibling steps named `__`, and consecutive siblings dispatch in parallel up to 8 at a time, minus any sibling that depends on another in the same group. Persisted events stay in batch-index order either way, so SSE replay is deterministic. Supported hosted tools are the generation and editing tools (`generate_image`, `edit_image`, `upscale_image`, `restore_photo`, `apply_style`, `refine_result`, `change_angle`, `generate_video`, `animate_photo`, `sound_to_video`, `video_to_video`, `generate_music`, `generate_speech`, `stitch_video`, `orbit_video`, `dance_montage`, `extend_video`, `replace_video_segment`, `overlay_video`, and `add_subtitles`), the media inspection tools (`analyze_image`, `analyze_video`, and `extract_metadata`), plus the hosted agent/control and manifest tools: `create_asset_manifest`, `inspect_asset`, `label_asset`, `map_assets_for_model`, `validate_asset_references`, `ask_clarifying_question`, and `finalize_response`. For a promptless image enlargement, use an `upscale_image` step with `sourceImageIndex` and either `scale: 2|3|4` or `targetLongestEdge`. The 8K and 16K profiles use `7680` and `15360` respectively; RTX VSR preserves aspect ratio and aligns both output edges to 8px. `generate_speech` is the spoken-audio step β€” narration, voiceover, a line of dialogue β€” as distinct from `generate_music`, which composes songs and instrumentals. Its `model` picks how the speaker is chosen: `"voice"` (the default) reads in one of nine studio voices named by `voice`, optionally restyled with `voiceDescription`; `"clone"` reproduces a voice from a recording and requires `voiceSourceIndex`; `"design"` invents a speaker from a written `voiceDescription` and takes no recording. Only `prompt` β€” the text to speak β€” is required. In a durable workflow, point `voiceSourceIndex` at a request media reference or bind the recording through a dependency, the same as any other audio input. ## [#](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#lora-steps)LoRA Steps `generate_image`, `edit_image`, `generate_video`, and `animate_photo` accept an ordered LoRA stack. `loras` holds the ids; `loraStrengths` is positional against it, so `loraStrengths[i]` applies to `loras[i]`. Order matters, because adapters apply in sequence and do not commute. Step arguments are schema-validated before anything dispatches, so these are hard `400`s rather than silent corrections: | Mistake | Result | | --- | --- | | More than 8 entries in `loras` or `loraStrengths` | `Argument "loras" must contain at most 8 items` | | `loras: []` | `Argument "loras" must contain at least 1 item` | | `loraStrengths` a different length than `loras` | `Arguments "loras" and "loraStrengths" must contain the same number of entries` | | `loraStrengths` without `loras` | `Argument "loraStrengths" requires "loras"` | Omitting `loraStrengths` entirely is valid and is the one supported way to leave strengths unset β€” every LoRA then applies at `1.0`. That is not "use the catalog default"; nothing downstream fills a per-LoRA default in. LoRAs are model-gated. A stack sent to a model that cannot load it is filtered out silently instead of failing the step, so select the model in the same step: | Step tool | Models that load LoRAs | | --- | --- | | `generate_image` | `model: "krea-2-turbo"` or `"dark-beast-krea2"` | | `edit_image` | `model: "krea-identity-edit"` or `"dark-beast-krea2-identity-edit"`; personal LoRAs also work with `"qwen"` | | `generate_video` | `videoModel: "minimax-h3-t2v"`, `"minimax-h3-t2v-turbo"`, `"minimax-h3-t2v-balanced"`, `"minimax-h3-fasth3-t2v-turbo"`, `"minimax-h3-fasth3-t2v-turbo-2stage"`, `"minimax-h3-r2v"`, `"minimax-h3-r2v-turbo"`, `"minimax-h3-r2v-balanced"`, `"minimax-h3-r2v-2stage"`, or `"minimax-h3-r2v-balanced-2stage"` | | `animate_photo` | `videoModel: "minimax-h3-i2v"`, `"minimax-h3-i2v-turbo"`, `"minimax-h3-i2v-balanced"`, `"minimax-h3-fasth3-i2v-turbo"`, `"minimax-h3-fasth3-i2v-turbo-2stage"`, `"minimax-h3-flf2v"`, `"minimax-h3-flf2v-turbo"`, `"minimax-h3-flf2v-balanced"`, `"minimax-h3-fasth3-flf2v-turbo"`, or `"minimax-h3-fasth3-flf2v-turbo-2stage"` | The `fasth3` selectors are the separate FastVideo VSA four-step engine β€” roughly twice as fast as the LightX2V Turbo modes and fixed to Euler/simple. FastH3 has no reference-to-video mode, which is why `generate_video` lists a FastH3 text-to-video selector but no FastH3 R2V. For two-stage reference-to-video, use `minimax-h3-r2v-2stage` (Standard) or `minimax-h3-r2v-balanced-2stage` (Balanced). ``` curl https://api.sogni.ai/v1/creative-agent/workflows \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: lora-portrait-001" \ -d '{ "input": { "title": "LoRA portrait", "steps": [ { "id": "portrait", "toolName": "generate_image", "arguments": { "prompt": "Close-up portrait, window light, 85mm", "model": "krea-2-turbo", "loras": ["krea2-realism", "krea2-skin-detail"], "loraStrengths": [0.8, 0.45] } } ] }, "token_type": "spark" }' ``` The video equivalent pairs the stack with an H3 mode and the trigger word: ``` { "id": "clip", "toolName": "generate_video", "arguments": { "prompt": "r34l1sm, a barista pulls an espresso as steam catches the light", "videoModel": "minimax-h3-t2v", "duration": 5, "loras": ["h3-realism-people"], "loraStrengths": [0.9] } } ``` Krea 2 image LoRAs are bipolar sliders: each id names its positive direction, a negative strength applies the opposite, and `0` disables it. Some LoRAs also need a trigger word: `h3-realism-people`, published on every H3 mode, wants `r34l1sm` near the front of the prompt, or the render returns as ordinary H3 with no error. Published ids, per-LoRA strength ranges, and maturity flags come from `GET /v1/loras/comfy?modelId=` β€” the canonical worker model id rather than the tool key, for example `?modelId=krea2_turbo_fp8_scaled` or `?modelId=minimax-h3-fl2va-fp8_i2v`. Filtering is per-id, not all-or-nothing: an id the model cannot load is dropped while the compatible remainder still applies, and only when nothing survives are the LoRA parameters left off the render entirely. The first render with an uncached LoRA takes longer to start while the worker downloads it. Unlimited subscribers can also pass ready [personal LoRAs](https://docs.sogni.ai/api-reference/personal-loras/) by their exact `personal-…` IDs, discovered through authenticated `GET /v1/loras/personal/catalog`. Personal LoRA strength must be greater than 0 and at most 1. Unlike public IDs, a personal ID sent with a model that cannot use it fails the step with `400` instead of being dropped. The `compose_workflow` and `compose_workflow_template` planners can emit LoRA steps too, but only when the brief asks for an effect a published id covers. ## [#](https://docs.sogni.ai/sogni-intelligence/creative-agent-workflows/#h3-reference-audio-policy)H3 Reference Audio Policy A `generate_video` step on `minimax-h3-r2v` or `minimax-h3-r2v-turbo` that passes `referenceVideoIndices` or `referenceAudioIndices` must also send `sourceAudioPolicy`. These H3 modes generate audio jointly with the picture, so a reference clip's soundtrack has no safe implicit role β€” the argument has no default, and omitting it fails the start with a `400` naming the argument rather than guessing. | Value | Use | | --- | --- | | `reuse_exact` | Keep the source audio itself. The correct choice for a specific, original, or trending song. | | `reference_only` | Generate new audio guided by the source. Use only when the caller explicitly wants newly generated audio. | | `replace` | Substitute different audio. Use only when the caller explicitly authorizes it. | `sourceAudioPolicy` is rejected on any other model β€” including the H3 text-to-video and image-conditioned modes β€” with `Argument "sourceAudioPolicy" is only supported by MiniMax H3 R2V models`. The two source-conditioned policies are also checked against the prompt, because the policy only takes effect if the prompt carries the matching official markers. `reuse_exact` requires an `[... audio reuse ...]` summary task, `