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.
Small scalars, text, and structured data travel inline:
{ "kind": "text", "value": "a brass key on black velvet" }{ "kind": "structured", "value": { "tags": ["key", "brass"] } }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:
{
"inputs": {
"prompt": { "kind": "text", "value": "isometric stone tower" },
"photo": { "kind": "image", "ref": "https://example.com/tower.jpg" }
}
}To feed an existing image into a node (e.g. an init port for image-to-image),
pass a ref artifact pointing at any fetchable URL.
Single-node runs (runs.node) are more lenient: value ports accept bare
scalars ("a prompt", 7, true) and data ports take artifacts.
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.
- 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.