🎨Creative-Agent Workflows

POST /v1/creative-agent/workflows starts a durable creative workflow directly. It does not ask the LLM to decide what to do. You provide the workflow kind and normalized input up front.

Use this endpoint when your application already knows the exact media operation to run and needs durable state, replayable event logs, SSE progress, or cancellation.

#Workflow Endpoints

All workflow routes require authentication. Starting a workflow requires API-key auth.

#Supported Start Kinds

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 completed, failed, or cancelled.

#Image To Video

For kind: "image_to_video", Sogni builds a plan with an image step followed by a video step. The generated image is passed to the video step as an explicit artifact dependency.

curl https://api.sogni.ai/v1/creative-agent/workflows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "image_to_video",
    "input": {
      "prompt": "A graphite robot sketch on a drafting table",
      "videoPrompt": "The camera pushes in as the sketch comes alive",
      "duration": 5,
      "imageModel": "flux2",
      "videoModel": "ltx23"
    },
    "token_type": "spark"
  }'

Representative response:

{
  "status": "success",
  "data": {
    "workflow": {
      "workflowId": "wf_image_to_video_...",
      "kind": "image_to_video",
      "status": "running",
      "input": {},
      "plan": {},
      "events": [],
      "artifacts": [],
      "createTime": 1773353812,
      "updateTime": 1773353812
    }
  }
}

#Hosted Tool Sequence

For exact backend tool execution without asking the chat model to select tools, use kind: "hosted_tool_sequence". Media-bearing arguments may use HTTPS artifact URLs, including presigned download URLs returned after Sogni image/media uploads.

curl https://api.sogni.ai/v1/creative-agent/workflows \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "hosted_tool_sequence",
    "input": {
      "title": "Seedance V2V",
      "steps": [
        {
          "id": "seedance_v2v",
          "toolName": "sogni_video_to_video",
          "arguments": {
            "prompt": "Transform the source clip into a polished perfume commercial with glass reflections",
            "reference_video_url": "https://...presigned-download-url...",
            "model": "seedance2",
            "control_mode": "seedance-v2v",
            "duration": 4
          }
        }
      ]
    },
    "token_type": "spark"
  }'

#Stream Events

curl https://api.sogni.ai/v1/creative-agent/workflows/wf_.../events/stream \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream"

The SSE stream replays known events on connect, then tails the persisted workflow record. It closes when the workflow reaches a terminal status.

EventSource cannot send the Authorization header. Use fetch with ReadableStream, or another HTTP client that can set headers, when consuming the stream from a browser.

#Cancel A Workflow

curl -X POST https://api.sogni.ai/v1/creative-agent/workflows/wf_.../cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Cancellation is idempotent. If the workflow is already terminal, the API returns the current snapshot with transitioned: false.

#Choosing Workflows

Use /v1/creative-agent/workflows when:

• Your app already knows the exact steps and tool arguments.
• You need durable workflow state, replayable event logs, SSE progress, or cooperative cancellation.
• You want to use uploaded Sogni artifact URLs or presigned HTTPS media URLs instead of inline chat data: URIs.
• You want deterministic orchestration rather than model-selected tools.
• You are building a production media pipeline where the UI should track each creative step independently of a chat response.

Use Chat Completions instead when an LLM should interpret the user's request and choose tools automatically.

For agent runtime or CLI-style integration, use the public Sogni Creative Agent Skill. It wraps Sogni media generation as an installable agent skill and CLI while the REST workflow API remains the durable backend integration surface.