Artifacts
The value envelope for run inputs and outputs — ref vs inline.
Every run input and output is an Artifact: a small envelope that pairs a
kind with either an inline value or a URL reference.
The two forms
Binary data — images, audio, video, files — travels by reference. ref is a
URL; fetch it to get the bytes:
{
"kind": "image",
"ref": "https://…/output.png",
"mimeType": "image/png",
"metadata": { "width": 1024, "height": 1024 }
}mimeType and metadata are optional.
Kinds
image, text, audio, video, float, int, boolean, embedding,
file, structured — matching the workflow input connector types.
Passing artifacts as inputs
Workflow run inputs (inputs on POST /v1/runs) are artifacts keyed by the
workflow's declared input names. kind is optional on the way in — the
workflow's input node (or, for runs.node, the node's port) already declares
the type, and the server fills it in:
{
"inputs": {
"prompt": { "value": "isometric stone tower" },
"photo": { "ref": "https://example.com/tower.jpg" }
}
}Sending kind explicitly is still accepted, and every artifact you get back
carries one — outputs are always complete envelopes.
To feed your own media into a node (e.g. an init port for image-to-image),
first turn it into an owned artifact — import a remote
URL server-side, or upload local bytes with the
signed-upload flow — and pass the returned ref artifact unchanged. In the
studio and on a model page, every image/audio/video/file input runs that same
signed upload for you: drop a file on the field, or pick one with its upload
button, and the field fills with the resulting ref.
Single-node runs (runs.node) are more lenient: value ports accept bare
scalars ("a prompt", 7, true) and data ports take artifacts.
A code node accepts FILE, IMAGE, AUDIO, or VIDEO only from a compatible
BlitFlow Artifact reference in the workflow graph. It does not accept an
external URL, data: URI, base64 value, or descriptor literal. See Binary
artifacts in code nodes.
Don't try to read image bytes out of an artifact's value — binary outputs
are always ref artifacts. Download the ref URL, and persist the bytes
yourself if you need them beyond the 30-day retention window below.
Storage and retention
Node outputs are served from blitflow's own storage: before a run records
a step result, any output the model provider returned is copied to blitflow
blob storage and the artifact's ref is rewritten to that URL. You never
receive a short-lived provider URL — output refs stay fetchable after the
provider's own links have expired.
Two retention rules apply:
- Run artifacts expire after 30 days. Outputs produced by a run are retained for 30 days from creation, then deleted. Download anything you want to keep longer.
- Temporary uploads and imports expire after 30 days. Media you bring in
via
/v1/artifacts/importor the signed-upload flow defaults to the same window (expiresAton the response says exactly when); passretention: "durable"for assets that should live forever. - Recipe assets don't expire. An asset that is part of a workflow's definition — e.g. an image set as a default value in the graph — lives as long as the workflow does, even if it started life as a run output or a temporary upload (a graph reference promotes it to durable).