Creative Workflows

Surface · Pre-planned execution

#Creative Workflows

Durable multi-step creative jobs with an explicit steps[] dependency graph. Use this when your application has already decided what to do — storyboards, image→video, batch generation. The API executes, persists state, streams SSE events, and supports cancel, resume, and reseed. (User-facing surfaces call these "cloud workflows".)

POST /v1/creative-agent/workflows Auth required

Start a durable creative workflow. Provide an inline input.steps plan or invoke a saved template by workflow_id + inputs. The two are mutually exclusive.

#Headers

Name	Type	In	Description
Idempotency-Key	string	header	Optional. `X-Idempotency-Key` also accepted. Max 192 chars.

#Body — inline steps

Name	Type	In	Description
input	object	body	Inline workflow plan. Allowed fields: `title`, `steps`. Required when `workflow_id` is absent.
input.title	string	body	Optional human-readable title for the run.
input.steps*	array	body	Array of step inputs. Each step: `id`, `toolName`, `arguments`, and an optional `dependsOn` array linking it to upstream artifacts.
workflow_id	string	body	Optional saved-template ID. Compiled server-side into a fresh `steps[]` before execution.
inputs	object	body	Object of typed input values when invoking a template. Keys match `WorkflowTemplate.inputs[].name`.
token_type	string	body	`spark`, `sogni`, or `auto`.
app_source	string	body	Optional caller label.
max_estimated_capacity_units	number	body	Hard ceiling on estimated capacity units. Over-budget submissions are rejected before persistence.
confirm_cost	boolean	body	Cost-confirmation gate. Submit with `false` to request an estimate — the API rejects with `400` and a structured `estimatedCapacity` body so you can show the user the cost. Resubmit with `true` to proceed.
media_references	array	body	Optional request media references available to `$input_media` bindings and negative media indices.

$ curl https://api.sogni.ai/v1/creative-agent/workflows \
  -H "Authorization: Bearer $SOGNI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "title": "Robot sketch → video",
      "steps": [
        {
          "id": "keyframe",
          "toolName": "generate_image",
          "arguments": { "prompt": "A graphite robot sketch on a drafting table" }
        },
        {
          "id": "clip",
          "toolName": "generate_video",
          "arguments": { "prompt": "Slow dolly-in on the keyframe.", "duration": 5 },
          "dependsOn": [{
            "sourceStepId": "keyframe",
            "sourceArtifactIndex": 0,
            "targetArgument": "referenceImageIndices",
            "transform": "image_index",
            "required": true
          }]
        }
      ]
    },
    "token_type": "auto",
    "max_estimated_capacity_units": 25,
    "confirm_cost": true
  }'

const wf = await sogni.workflows.start({
  input: {
    title: 'Robot sketch → video',
    steps: [
      {
        id: 'keyframe',
        toolName: 'generate_image',
        arguments: { prompt: 'A graphite robot sketch on a drafting table' },
      },
      {
        id: 'clip',
        toolName: 'generate_video',
        arguments: { prompt: 'Slow dolly-in on the keyframe.', duration: 5 },
        dependsOn: [{
          sourceStepId: 'keyframe',
          sourceArtifactIndex: 0,
          targetArgument: 'referenceImageIndices',
          transform: 'image_index',
          required: true,
        }],
      },
    ],
  },
  max_estimated_capacity_units: 25,
  confirm_cost: true,
});

import os, requests, uuid

resp = requests.post(
    "https://api.sogni.ai/v1/creative-agent/workflows",
    headers={
        "Authorization": f"Bearer {os.environ['SOGNI_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "input": {
            "title": "Robot sketch → video",
            "steps": [
                {
                    "id": "keyframe",
                    "toolName": "generate_image",
                    "arguments": {"prompt": "A graphite robot sketch on a drafting table"},
                },
                {
                    "id": "clip",
                    "toolName": "generate_video",
                    "arguments": {"prompt": "Slow dolly-in on the keyframe.", "duration": 5},
                    "dependsOn": [{
                        "sourceStepId": "keyframe",
                        "sourceArtifactIndex": 0,
                        "targetArgument": "referenceImageIndices",
                        "transform": "image_index",
                        "required": True,
                    }],
                },
            ],
        },
        "max_estimated_capacity_units": 25,
        "confirm_cost": True,
    },
)

#Response

{
  "status": "success",
  "data": {
    "workflow": {
      "workflowId": "wf_…",
      "status": "queued",
      "input": { "title": "Robot sketch → video", "steps": [ /* … */ ] },
      "events": []
    }
  }
}

Active-workflow cap. Default 3 concurrent workflows per wallet. The 4th returns 409; cancel or finish one before submitting another.

GET /v1/creative-agent/workflows Auth required

List the caller's workflows.

#Query parameters

Name	Type	In	Description
offset	integer	query	Default `0`.
limit	integer	query	Default `20`, max `100`.

#Response

{
  "status": "success",
  "data": { "workflows": [ /* … */ ], "next": 20 }
}

GET /v1/creative-agent/workflows/:id Auth required

Read a single workflow snapshot.

GET /v1/creative-agent/workflows/:id/events Auth required

Read the persisted event log for a workflow.

GET /v1/creative-agent/workflows/:id/events/stream Auth required

Server-Sent Events stream of workflow events. Replays persisted history, then streams live updates until terminal.

POST /v1/creative-agent/workflows/:id/resume Auth required

Resume a workflow from persisted state (e.g. after a waiting state clears).

#Body

Name	Type	In	Description
token_type	string	body	Optional. Overrides the original run's billing preference.
app_source	string	body	Optional caller label.

POST /v1/creative-agent/workflows/:id/confirm-cost Auth required

Approve or reject the cost preview for a workflow paused with cost_approval_required (e.g. a template run, which authorizes cost on start). resume does not release a cost-approval pause — use this endpoint. Rate-limited to 30/minute per wallet.

#Body

Name	Type	In	Description
decision*	string	body	`"confirm"` or `"cancel"`.
acceptedCostPreview*	object	body	Required for `decision: "confirm"`. Echo the persisted preview — `{ totalEstimatedCapacityUnits, tokenType, validityUntil }`; a stale or mismatched value returns `409` (a missing or malformed object returns `400`).
Idempotency-Key	string	header	Optional. `X-Idempotency-Key` also accepted; a replay returns the prior result.

#Response

{
  "status": "success",
  "data": { "workflow": { "…": "…" }, "decision": "confirm", "authorization": { "…": "…" } }
}

POST /v1/creative-agent/workflows/:id/cancel Auth required

Cooperative cancel. Flips the workflow to cancelled and emits a cancel event for SSE replay.

POST /v1/creative-agent/workflows/:id/reseed Auth required

Clone a completed workflow with fresh RNG seeds — "alternate takes" without retyping a plan. Returns a new workflowId.

#Body

Name	Type	In	Description
seed_overrides	object	body	Optional per-step seed overrides. Omit to let the server generate fresh seeds for every step.
token_type	string	body	Optional billing preference.
app_source	string	body	Optional caller label.