Concepts · Artifacts

Artifacts

Artifacts are the durable outputs produced by workflow runs — visual, video, research, or knowledge. Every artifact carries provenance back to the workflow and run that produced it. An artifact that prints a checkable fact also carries the passages it was drawn from and the source policy that approved them.

Produced and consumed

An artifact is a first-class value: a run can both produce one and consume one. A workflow is, in effect, a function over artifacts — it takes zero or more artifacts (plus intake) and produces one.

Workflow : Artifact* -> Artifact

This is why composition works two ways. A workflow can obtain an input artifact by generating it inline (a sub-workflow) or by accepting one you already have (an artifact input).

Artifact classes

Provenance

Every artifact references the runId and templateId that produced it, so you can trace prompt, provider, model, timing, cost, and review state from any persisted output through GET /v1/runs/{runId}.

{
  "id": "artifact-0dc32dbb",
  "runId": "run-a1b2c3d4",
  "templateId": "generate-clip-art-asset",
  "artifactClass": "visual",
  "status": "review",
  "content": {
    "type": "image",
    "url": "https://images.esy.com/artifacts/clip-art/artifact-0dc32dbb/processed.webp",
    "storageKey": "artifacts/clip-art/artifact-0dc32dbb/processed.webp",
    "mimeType": "image/webp",
    "width": 1024,
    "height": 1024
  },
  "createdAt": "2026-05-16T22:14:43.711Z"
}

Status values

Visual artifacts

A visual artifact has two files: raw (model output) and processed (post background removal and any QA passes). Both are stored as WebP. The artifact response includes the public url for the processed file; the storageKey is stable and safe to persist on your side.

artifacts/{artifactType}/{artifactId}/raw.webp
artifacts/{artifactType}/{artifactId}/processed.webp

Video artifacts

A video artifact is one MP4. Its content carries the public url, a stable storageKey, the mimeType, and the length in durationSeconds, alongside the frame size and shape. A generated clip also carries the prompt and references it was rendered from.

A film cut (artifactType: "film-cut", from build-film-cut) is several clips joined into one film — think of an editor’s cut, not a new render. Nothing in it is invented: each clip is trimmed to the seconds you chose, fitted to one frame size and frame rate (letterboxed, never stretched), and joined in order. So it adds two things a single clip doesn’t have:

• segments — where every shot sits in the film (at) and which part of which clip it is (url, start, seconds). It is the edit decision list, so you can map any moment of the film back to the take it came from.
• measuredSeconds — how long the encoded file actually runs, read from the file rather than added up. The artifact’s length check compares it with the kept seconds; a film that comes out short is held for review instead of shipped.

Film cuts are silent (generateAudio: false). Sound belongs to the whole film, not to each clip, so it is added in a later step rather than stitched together from clips that each had their own.

{
  "id": "artifact-5b1f0c2e",
  "runId": "run-3e9a7d10",
  "templateId": "build-film-cut",
  "artifactClass": "video",
  "artifactType": "film-cut",
  "status": "ready",
  "content": {
    "type": "video",
    "url": "https://images.esy.com/artifacts/tool/run-3e9a7d10/step-1.mp4",
    "storageKey": "artifacts/tool/run-3e9a7d10/step-1.mp4",
    "mimeType": "video/mp4",
    "durationSeconds": 60,
    "measuredSeconds": 60.04,
    "width": 1280,
    "height": 720,
    "fps": 24,
    "aspectRatio": "16:9",
    "generateAudio": false,
    "segments": [
      { "index": 0, "url": "https://images.clip.art/animations/…/take-1.mp4", "start": 0.0, "seconds": 5, "at": 0.0 },
      { "index": 1, "url": "https://images.clip.art/animations/…/take-4.mp4", "start": 0.6, "seconds": 4, "at": 5.0 }
    ]
  }
}

Research artifacts

A research artifact is structured text rather than a file. Its content carries a title, a summary, an ordered list of sections (heading + body), and a list of sources. Sourcing is model-derived today; web-search-backed citations land in a later phase.

{
  "id": "artifact-7c4e91aa",
  "runId": "run-9f8e7d6c",
  "templateId": "generate-research-report",
  "artifactClass": "research",
  "status": "review",
  "content": {
    "type": "research-report",
    "title": "The economics of desalination",
    "summary": "A structured synthesis of cost drivers, energy intensity, and...",
    "sections": [
      { "heading": "Cost drivers", "body": "..." },
      { "heading": "Energy intensity", "body": "..." }
    ],
    "sources": ["IEA 2025 desalination outlook", "..."]
  },
  "createdAt": "2026-05-29T15:02:11.004Z"
}

Research artifacts are reusable on their own and as inputs to other workflows. When a workflow composes a research report through a sub-workflow, the produced artifact (for example, an infographic) carries a sourceReportArtifactId back-reference to the report it was built from.

Artifacts as inputs

A workflow template can declare that it accepts an existing artifact as input. The author adds an intake field of type artifactReference, constrained to the artifact class and type the workflow knows how to read — so the field has a defined consumer and the supplied value can be validated.

{
  "name": "sourceReport",
  "type": "artifactReference",
  "required": false,
  "description": "An existing research report to visualize",
  "artifactClass": "research",
  "artifactType": "research-report"
}

At run time you pass the chosen artifact’s id in intake. The engine loads that artifact and exposes its content at inputs.{field}, which steps reference like any other context — for example {inputs.sourceReport.summary}.

{
  "templateId": "generate-research-infographic",
  "intake": {
    "topic": "The history of dinosaurs",
    "aspectRatio": "3:4",
    "sourceReport": "artifact-7c4e91aa"
  }
}

Generate or supply

A step can declare that a supplied artifact satisfies it. When the input is present, the step is skipped and the supplied artifact fills its output slot; when it is absent, the step runs normally — for example, generating the artifact through a sub-workflow. Downstream steps read the same reference either way, so “generate a fresh one” and “use this existing one” are interchangeable to the rest of the workflow.

See the compose with artifact inputs guide for a worked example.

Artifacts made of artifacts

A clip art pack or a story book is one thing made of many artifacts. That whole is a collection: its members keep their ids through every re-roll, and its cover, publishing and cost are read from all of its members together.

Knowledge artifacts have their own content shape; it will be documented here when the class ships its public contract.