API referenceGeneration

Generation Recipes

Need a single image, video clip, or music track without an LLM in the loop? Submit a one-step creative workflow. The same POST /v1/creative-agent/workflows endpoint that runs multi-step storyboards also runs single hosted-tool calls: no chat session, no planning round. You bring the idea and the arguments; the server validates the step and dispatches the work. Follow progress over SSE and read the artifact URL from the completed workflow.

#Generate an image

POST /v1/creative-agent/workflows Auth required

Single-step text-to-image. This example uses krea-2-turbo. Other model values include z-turbo, z-image, dark-beast-krea2, chroma-v46-flash, chroma1-hd, qwen-2512, qwen-2512-lightning, community SDXL checkpoints, and the Premium Spark models gpt-image-2, gpt-image-2.5-sunburst, and gpt-image-2.5-flare. See GET /v1/model-catalog?mediaType=image for what each model offers. The OpenAI-compatible /v1/models endpoint lists LLMs, not image models.

curl https://api.sogni.ai/v1/creative-agent/workflows \
  -H "Authorization: Bearer $SOGNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "title": "Neon Tokyo alley",
      "steps": [
        {
          "id": "image1",
          "toolName": "generate_image",
          "arguments": {
            "prompt": "A cinematic neon-lit Tokyo alley during rain, shallow depth of field",
            "model": "krea-2-turbo"
          }
        }
      ]
    }
  }'

const wf = await sogni.workflows.start({
  input: {
    title: 'Neon Tokyo alley',
    steps: [
      {
        id: 'image1',
        toolName: 'generate_image',
        arguments: {
          prompt: 'A cinematic neon-lit Tokyo alley during rain, shallow depth of field',
          model: 'krea-2-turbo',
        },
      },
    ],
  },
});

for await (const frame of sogni.workflows.streamEvents(wf.workflowId)) {
  if (frame.event === 'workflow_completed') break;
}

import os, requests

resp = requests.post(
    "https://api.sogni.ai/v1/creative-agent/workflows",
    headers={"Authorization": f"Bearer {os.environ['SOGNI_API_KEY']}"},
    json={
        "input": {
            "title": "Neon Tokyo alley",
            "steps": [
                {
                    "id": "image1",
                    "toolName": "generate_image",
                    "arguments": {
                        "prompt": "A cinematic neon-lit Tokyo alley during rain, shallow depth of field",
                        "model": "krea-2-turbo",
                    },
                }
            ],
        }
    },
)
workflow = resp.json()["data"]["workflow"]

Poll GET /v1/creative-agent/workflows/:id or subscribe to /v1/creative-agent/workflows/:id/events/stream for the SSE event stream. The completed artifact URL is at workflow.steps[0].artifacts[0].url.

#Generate a video from a prompt

POST /v1/creative-agent/workflows Auth required

Single-step text-to-video. Sogni-native models: ltx25 (default), ltx23 (rollback), wan22, and MiniMax H3 selectors such as minimax-h3-t2v, minimax-h3-t2v-turbo, minimax-h3-fasth3-t2v-turbo, and minimax-h3-r2v-turbo. Premium Spark models: seedance2 and seedance2-mini, seedance2-5, happyhorse-1.1-t2v, happyhorse-1.1-i2v, and happyhorse-1.1-r2v, wan3.0-video, and wan3.0-spicy-video. Legacy seedance2-fast requests route to seedance2-mini. Other videoModel values return 400, and the outputScale argument is no longer accepted; use a MiniMax H3 -2stage selector for enlarged output.

curl https://api.sogni.ai/v1/creative-agent/workflows \
  -H "Authorization: Bearer $SOGNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "title": "Neon city flythrough",
      "steps": [
        {
          "id": "clip",
          "toolName": "generate_video",
          "arguments": {
            "prompt": "A slow drone fly-through above a rain-soaked neon city, cinematic lighting",
            "videoModel": "ltx25",
            "duration": 5
          }
        }
      ]
    }
  }'

const wf = await sogni.workflows.start({
  input: {
    title: 'Neon city flythrough',
    steps: [
      {
        id: 'clip',
        toolName: 'generate_video',
        arguments: {
          prompt: 'A slow drone fly-through above a rain-soaked neon city, cinematic lighting',
          videoModel: 'ltx25',
          duration: 5,
        },
      },
    ],
  },
});

import os, requests

resp = requests.post(
    "https://api.sogni.ai/v1/creative-agent/workflows",
    headers={"Authorization": f"Bearer {os.environ['SOGNI_API_KEY']}"},
    json={
        "input": {
            "title": "Neon city flythrough",
            "steps": [
                {
                    "id": "clip",
                    "toolName": "generate_video",
                    "arguments": {
                        "prompt": "A slow drone fly-through above a rain-soaked neon city, cinematic lighting",
                        "videoModel": "ltx25",
                        "duration": 5,
                    },
                }
            ],
        }
    },
)

Duration defaults to 5 seconds. Ranges: LTX 2.5 and 2.3, 2–20 s; Seedance 2.0 and Mini, 4–15 s; Seedance 2.5, 4–30 s; HappyHorse 1.1, 3–15 s; Wan 3, 2–30 s. MiniMax H3 clamps any requested length to about 5.2–15.1 s on its 24 fps frame grid and bills the rendered length. generate_video with loose referenceImageIndices or referenceVideoIndices and no videoModel uses MiniMax H3 Reference-to-Video Turbo.

#Animate a generated keyframe

POST /v1/creative-agent/workflows Auth required

Two-step composition: generate_image emits a keyframe, then animate_photo uses it as the first frame through a dependsOn binding. To animate your own image instead, list it in media_references and set sourceImageIndex: -1.

curl https://api.sogni.ai/v1/creative-agent/workflows \
  -H "Authorization: Bearer $SOGNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "title": "Robot sketch to video",
      "steps": [
        {
          "id": "keyframe",
          "toolName": "generate_image",
          "arguments": { "prompt": "A graphite robot sketch on a drafting table" }
        },
        {
          "id": "clip",
          "toolName": "animate_photo",
          "arguments": { "prompt": "Slow dolly-in as the sketch comes alive.", "videoModel": "ltx25", "duration": 5 },
          "dependsOn": [{
            "sourceStepId": "keyframe",
            "sourceArtifactIndex": 0,
            "targetArgument": "sourceImageIndex",
            "transform": "image_index",
            "required": true
          }]
        }
      ]
    }
  }'

const wf = await sogni.workflows.start({
  input: {
    title: 'Robot sketch to video',
    steps: [
      {
        id: 'keyframe',
        toolName: 'generate_image',
        arguments: { prompt: 'A graphite robot sketch on a drafting table' },
      },
      {
        id: 'clip',
        toolName: 'animate_photo',
        arguments: { prompt: 'Slow dolly-in as the sketch comes alive.', videoModel: 'ltx25', duration: 5 },
        dependsOn: [{
          sourceStepId: 'keyframe',
          sourceArtifactIndex: 0,
          targetArgument: 'sourceImageIndex',
          transform: 'image_index',
          required: true,
        }],
      },
    ],
  },
});

import os, requests

resp = requests.post(
    "https://api.sogni.ai/v1/creative-agent/workflows",
    headers={"Authorization": f"Bearer {os.environ['SOGNI_API_KEY']}"},
    json={
        "input": {
            "title": "Robot sketch to video",
            "steps": [
                {
                    "id": "keyframe",
                    "toolName": "generate_image",
                    "arguments": {"prompt": "A graphite robot sketch on a drafting table"},
                },
                {
                    "id": "clip",
                    "toolName": "animate_photo",
                    "arguments": {"prompt": "Slow dolly-in as the sketch comes alive.", "videoModel": "ltx25", "duration": 5},
                    "dependsOn": [{
                        "sourceStepId": "keyframe",
                        "sourceArtifactIndex": 0,
                        "targetArgument": "sourceImageIndex",
                        "transform": "image_index",
                        "required": True,
                    }],
                },
            ],
        }
    },
)

#Generate music

POST /v1/creative-agent/workflows Auth required

Single-step text-to-music. The default model is MiniMax Music 3 (music3); set model: "turbo" or "sft" for ACE-Step. duration accepts 10–600 seconds (default 30) and is a ceiling for Music 3, which composes up to about 5 minutes. For vocal songs, compose lyrics first with compose_lyrics (synchronous) and pass them as arguments.lyrics.

curl https://api.sogni.ai/v1/creative-agent/workflows \
  -H "Authorization: Bearer $SOGNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "title": "Synthwave loop",
      "steps": [
        {
          "id": "track",
          "toolName": "generate_music",
          "arguments": {
            "prompt": "Mid-tempo synthwave with arpeggiated bass and warm pads, 90 BPM",
            "duration": 30
          }
        }
      ]
    }
  }'

const wf = await sogni.workflows.start({
  input: {
    title: 'Synthwave loop',
    steps: [
      {
        id: 'track',
        toolName: 'generate_music',
        arguments: {
          prompt: 'Mid-tempo synthwave with arpeggiated bass and warm pads, 90 BPM',
          duration: 30,
        },
      },
    ],
  },
});

import os, requests

resp = requests.post(
    "https://api.sogni.ai/v1/creative-agent/workflows",
    headers={"Authorization": f"Bearer {os.environ['SOGNI_API_KEY']}"},
    json={
        "input": {
            "title": "Synthwave loop",
            "steps": [
                {
                    "id": "track",
                    "toolName": "generate_music",
                    "arguments": {
                        "prompt": "Mid-tempo synthwave with arpeggiated bass and warm pads, 90 BPM",
                        "duration": 30,
                    },
                }
            ],
        }
    },
)

Going further. Direct generation uses the same persisted workflow runtime as multi-step jobs: every direct call gets a workflowId, an SSE event stream, and cancel, resume, and reseed support. See Creative Workflows for the full surface, or Chat Completions if you want the LLM to choose the tool and arguments from a natural-language prompt instead.