Generation Recipes

Quick recipes

#Direct generation

Need a single image, video clip, or music track and don't want an LLM in the loop? Submit a one-step creative workflow. The same POST /v1/creative-agent/workflows endpoint that powers multi-step storyboards also runs single hosted-tool calls — no chat session, no LLM 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; select image models from GET /v1/model-catalog?mediaType=image. 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 event of sogni.workflows.streamEvents(wf.workflowId)) {
  if (event.type === '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 on workflow.steps[0].artifacts[0].url.

#Generate a video from a prompt

POST /v1/creative-agent/workflows Auth required

Single-step text-to-video. Common models: ltx25 (default Sogni-native model), ltx23 (explicit rollback), wan22, seedance2 / seedance2-mini, or happyhorse-1.1-t2v / happyhorse-1.1-i2v / happyhorse-1.1-r2v (Premium Spark only). Legacy seedance2-fast requests route to the faster, lower-cost seedance2-mini.

$ 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,
                    },
                }
            ],
        }
    },
)

#Image-to-video (animate a reference image)

POST /v1/creative-agent/workflows Auth required

Two-step composition: first generate_image emits a keyframe, then generate_video animates from it via an in-band dependsOn binding.

$ 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 → 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 as the sketch comes alive.", "duration": 5 },
          "dependsOn": [{
            "sourceStepId": "keyframe",
            "sourceArtifactIndex": 0,
            "targetArgument": "referenceImageIndices",
            "transform": "image_index",
            "required": 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 as the sketch comes alive.', duration: 5 },
        dependsOn: [{
          sourceStepId: 'keyframe',
          sourceArtifactIndex: 0,
          targetArgument: 'referenceImageIndices',
          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 → 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 as the sketch comes alive.", "duration": 5},
                    "dependsOn": [{
                        "sourceStepId": "keyframe",
                        "sourceArtifactIndex": 0,
                        "targetArgument": "referenceImageIndices",
                        "transform": "image_index",
                        "required": True,
                    }],
                },
            ],
        }
    },
)

#Generate music

POST /v1/creative-agent/workflows Auth required

Single-step text-to-music using the ACE-Step audio family. 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, SSE event stream, cancel, resume, and reseed support. See Creative Workflows for the full surface; see Chat Completions if you want the LLM to choose the tool and arguments from a natural-language prompt instead.