Quickstart

This page takes you from nothing to a file on your disk: you create an API key, find a workflow, run it, wait for it to finish, and download what it made. Every step shows the request in curl, TypeScript and Python. The last section puts the whole thing in one script.

1. Create an API key#

1. Sign in to Sushibelt and open Team settings. Under Connections, choose API keys. Only team owners and admins see this page.
2. Type a name that says where the key will live, for example quickstart.
3. Optionally, type a Monthly cap in credits. The key stops starting runs once it has spent that much in a calendar month. See Cap your spend.
4. Leave every scope unselected for now: a key with no scopes selected has all of them. See Scopes for narrower keys.
5. Choose Create key, then Copy. The full key is shown once. If you lose it, revoke it and create another.

Put the key in an environment variable, so it never sits in your code:

export SUSHIBELT_API_KEY="sk_live_YOUR_KEY"

2. Find a workflow to run#

A workflow is a graph of steps you build on the canvas. List the ones your key can run with List workflows:

curl "https://app.sushibelt.ai/api/v1/workflows" \
  -H "Authorization: Bearer $SUSHIBELT_API_KEY"

{
  "workflows": [
    {
      "id": "3f1c9a52-8d4e-4b7a-9c61-2e5f0d7a1b90",
      "name": "Fox portrait",
      "description": null,
      "status": "active",
      "updated_at": "2026-09-29T09:12:44Z"
    }
  ]
}

Copy the id of the workflow you want. If the list is empty, your team has no workflows yet. Build one on the canvas in the app: the simplest is a Text node wired to an Image generator. You can also create one from code: see Workflow format.

3. Start a run#

Send the workflow's id to Run a workflow. An empty body runs the workflow exactly as it was built. To change its text for this run, see Pass inputs to a run.

WORKFLOW_ID="YOUR_WORKFLOW_ID"

curl -X POST "https://app.sushibelt.ai/api/v1/workflows/$WORKFLOW_ID/runs" \
  -H "Authorization: Bearer $SUSHIBELT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

{
  "jobId": "8b2d6f10-4c3a-4e59-a7d2-91f0c3e8b5a4",
  "workflowId": "3f1c9a52-8d4e-4b7a-9c61-2e5f0d7a1b90",
  "status": "queued",
  "estimatedCredits": 4,
  "stepsCount": 2
}

Keep the jobId: it is the run's id. estimatedCredits is what the run should cost. Before anything runs, Sushibelt holds enough credits to cover it; each step is then charged as it finishes, and the unused part of the hold is released at the end. One credit is US$0.01.

If the answer is 402, your team does not have enough credits, or a limit stopped the run. If it is 409, the workflow already has a run in progress. Handle errors and retries covers every answer.

4. Wait for it to finish#

Read the run with Get a run every few seconds until its status is completed or failed. progress is the share of steps that have finished, from 0 to 100.

JOB_ID="YOUR_JOB_ID"

curl "https://app.sushibelt.ai/api/v1/runs/$JOB_ID" \
  -H "Authorization: Bearer $SUSHIBELT_API_KEY"

{
  "jobId": "8b2d6f10-4c3a-4e59-a7d2-91f0c3e8b5a4",
  "status": "completed",
  "progress": 100,
  "steps": [
    { "node_id": "0d9e…", "step_type": "TextEntry", "status": "completed" },
    { "node_id": "7c41…", "step_type": "DiffusionWorker", "status": "completed" }
  ],
  "output": [
    {
      "node_id": "7c41…",
      "step_type": "DiffusionWorker",
      "result": {
        "images": [{ "url": "https://example.com/files/0.png" }]
      },
      "licence": {
        "commercial_use": "yes",
        "models": [
          {
            "node_id": "7c41…",
            "provider_key": "fal_ai",
            "model": "flux-schnell",
            "licence": "Apache-2.0",
            "licence_url": "https://www.apache.org/licenses/LICENSE-2.0",
            "commercial_use": "yes",
            "terms_url": null,
            "stamped_at": "2026-09-29T09:14:02Z"
          }
        ]
      }
    }
  ]
}

To be told when the run ends instead of asking, pass a callbackUrl when you start it. See Poll or get a webhook.

5. Download the output#

output lists what the last steps of the workflow produced. Each result holds the step's files: an image step gives images, a list of objects with a url; a 3D step gives model_mesh with a url; an audio step gives audio with a url; a text step gives text. A preview step at the end of a workflow, such as an image gallery, passes on what it received, so the files sit further inside its result.

Download the files soon after the run completes. The links are temporary. Your team's library keeps its own copy of each file for 7 days; see Outputs and how long they are kept.

The whole script#

The same five steps as one program. Set SUSHIBELT_API_KEY, replace YOUR_WORKFLOW_ID, and run it. It saves each file as output-0.png, output-1.glb and so on, in the folder you run it from.

#!/usr/bin/env bash
# Needs curl and jq. Replace YOUR_WORKFLOW_ID with an id from "List workflows".
set -euo pipefail
: "${SUSHIBELT_API_KEY:?Set SUSHIBELT_API_KEY to your key first}"
API="https://app.sushibelt.ai/api/v1"
WORKFLOW_ID="YOUR_WORKFLOW_ID"

# 1. Start the run
RES=$(curl -s -X POST "$API/workflows/$WORKFLOW_ID/runs" \
  -H "Authorization: Bearer $SUSHIBELT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}')
JOB_ID=$(echo "$RES" | jq -r '.jobId // empty')
if [ -z "$JOB_ID" ]; then echo "Run refused: $RES"; exit 1; fi
echo "Run $JOB_ID started, estimated $(echo "$RES" | jq -r '.estimatedCredits') credits"

# 2. Poll every 5 seconds, for at most 15 minutes
for _ in $(seq 1 180); do
  sleep 5
  RUN=$(curl -s "$API/runs/$JOB_ID" -H "Authorization: Bearer $SUSHIBELT_API_KEY")
  STATUS=$(echo "$RUN" | jq -r '.status')
  echo "status: $STATUS ($(echo "$RUN" | jq -r '.progress')%)"
  case "$STATUS" in completed|failed|cancelled|stopped) break ;; esac
done
if [ "$STATUS" != "completed" ]; then echo "$RUN" | jq '.steps'; exit 1; fi

# 3. Download every image, mesh and audio file in the output
i=0
for URL in $(echo "$RUN" | jq -r '[.output[].result | .. | objects
    | (.images[]?, .audio?, .model_mesh?) | objects | .url | strings] | unique[]'); do
  NAME="${URL%%\?*}"
  FILE="output-$i.${NAME##*.}"
  curl -s -L -o "$FILE" "$URL"
  echo "saved $FILE"
  i=$((i + 1))
done

• The curl version needs jq.
• The TypeScript version runs as an ES module on Node 18 or later, for example with npx tsx quickstart.mts.
• The Python version needs the requests package.