Concepts

The words the API and these docs use, and what each one means for your code. Read it once; every guide assumes it.

Workflows#

A workflow is a saved graph of nodes: a prompt, a model that makes an image from it, a step that commits the image to a repository. You wire it on the canvas in the app, or send its steps to Create a workflow.

Workflows are organised in three levels, all inside your team:

• A project groups related work, such as one game.
• An agent lives in a project and holds one or more workflows, which are versions of the same job. One of them is the agent's active workflow: the one that runs when you call Run an agent.
• A workflow belongs to one agent.

Run a workflow by its own id when you want that exact version. Run an agent when you want whichever version your team has made active, so that editing the agent in the app changes what your code runs without a code change.

In the app, the ids are in the address bar: /your-team/workspace/PROJECT_ID/AGENT_ID/canvas.

Runs#

A run is one execution of a workflow. Its id is the jobId you get back when you start it. A workflow can have one run in progress at a time: starting another answers 409 with the id of the run in progress.

Once a run's steps exist, its status follows them: processing while any step is left, failed as soon as one fails, completed when all have finished. Treat completed and failed as the end of a run. If someone stops a run in the app, its steps stop moving and no webhook is sent, so give any wait in your code a time limit.

Steps#

A step is one node's execution inside a run. Steps are what you are charged for. Get a run lists every step with its node_id (the node's id on the canvas), its step_type (the node type) and its status.

Credits#

A credit is the unit you pay in. One credit is US$0.01. Credits belong to your team, and anyone on the team who can run workflows spends them, as does every API key the team creates. Buy them in the app under Team settings → Balance.

What a run costs#

• Estimated before. Starting a run answers with estimatedCredits.
• Held. Before anything runs, Sushibelt holds enough credits to cover the run. If your balance cannot cover the hold, the run does not start and the answer is 402 with the credits it needs in required.
• Charged per step. Each step is charged when it finishes: what the model costs plus Sushibelt's markup. Steps that run no model, such as a text input or a preview, cost nothing.
• Released after. When the run ends, whatever is left of the hold goes back to your balance.
• Refunded on failure. If a run fails, every step that did not finish is refunded. Steps that finished stay charged: their outputs exist.

Limits you can set#

• A monthly cap on an API key: once the key has spent that much this month, it cannot start runs.
• A per-step credit ceiling for your team: no single step may cost more.
• A hard cap on a project: a run that would take the project past it does not start.
• Draft runs: a cheaper pass for trying a workflow out.

Cap your spend explains each one. The credit terms cover expiry and refunds.

Outputs and how long they are kept#

A run's output is what the workflow's last steps produced: the steps no other step reads from. It is empty until they finish. Each entry has the step's node_id, its step_type, a result and, when a model made it, a licence.

The shape of result depends on the node type:

• An image step: images, a list of objects, each with a url.
• A 3D step: model_mesh, an object with a url.
• An audio step: audio, an object with a url.
• A text step: text, a string.
• A delivery step: where each file was committed. See Deliver to GitHub, GitLab or Unity.
• A preview step, such as an image gallery: what it received, further inside its result.

How long a file can be fetched:

• The link in result is temporary. Some links point to the provider's storage and last as long as that provider keeps the file; links to Sushibelt's own storage stop working two hours after the step ran. Download what you need as soon as the run completes.
• Your team's library keeps a copy for 7 days. Each file is copied into the library in the app, and deleted 7 days after it was made. If your team's storage is full, new files are kept for 24 hours only and do not count against it.

Models, providers and makers#

• A model is a specific thing that generates: an image model, a text model, a 3D model.
• A provider is the company whose API runs it. The same model can be offered by more than one provider.
• A maker is who trained the model, and is often not the provider.

A node on the canvas names the model it runs, and Sushibelt sends the step to a provider that serves it. The run's licence records which provider and model made each output. Browse them on the models page.

If your team has its own account with a provider, add your key and Sushibelt calls that provider with it. You pay the provider directly and Sushibelt charges only a small fee per step. See Bring your own provider key.

Licences#

Every output a model made carries the licence it ships under: each model it came from, that model's licence as it stood when the step ran, and one verdict on commercial use for the whole output — as strict as the strictest model in its chain. See Use a model's licence in your product.

The library#

The library is where your team's outputs are stored in the app, whether a run was started from the canvas or from the API. Open it from the app's navigation to preview, download or reuse a file on the canvas.