Core concepts · Intake

Intake

Intake is what you hand a run. Each workflow declares the fields it accepts, and Esy validates your payload against that declaration before a single provider call is made — so a typo costs you a 422 rather than a render.

Reading the schema

Fetch any workflow’s contract and you get its intakeSchema: a flat list of fields, each with a type, a required flag, and — where the field is constrained — its allowed values and default.

{
  "fields": [
    {
      "name": "prompt",
      "type": "string",
      "required": true,
      "description": "Subject of the coloring page"
    },
    {
      "name": "aspectRatio",
      "type": "enum",
      "required": true,
      "default": "3:4",
      "options": ["3:4", "1:1", "4:3"]
    },
    {
      "name": "quality",
      "type": "enum",
      "required": false,
      "default": "medium",
      "options": ["low", "medium", "high", "xhigh", "max"]
    }
  ]
}

Field types you will meet:

When it does not validate

Every problem is named, so you should never have to guess which field was wrong. This is the single most common error against the API.

HTTP 422

{
  "detail": {
    "error": "intake_invalid",
    "fields": [
      "intake.prompt is required",
      "intake.categories is required"
    ]
  }
}

Unknown keys are currently logged rather than rejected — do not rely on that as permission to send extra fields. See Errors for the full list.

Artifact inputs

Some workflows take another artifact as input — an infographic built from a research report, an edit applied to an existing image. Those fields have type artifactReference and usually constrain the artifactType they accept.

{
  "name": "sourceReport",
  "type": "artifactReference",
  "required": true,
  "artifactType": "research-report",
  "description": "The report to turn into an infographic"
}

You pass an artifact id, and Esy checks that it exists, that it is the right type, and that it is inside a workspace you can reach — before the run starts. A workflow can also declare that a step may produce the input if you do not supply one; see Compose with artifact inputs.

The rule behind the schemas

Once you have read a few intake schemas, you will notice something: they ask for results, not methods. That is deliberate, and it is the design rule that explains most of what you will otherwise find arbitrary.

Every run answers two questions, and they belong to different layers:

You ask for “a picture with a see-through background”. Whether the model renders transparency directly or Esy renders normally and keys the background out afterwards is a kitchen decision — it depends on which model is bound today and what that model can do.

Why it is built this way

A mechanism field fails twice over. First, it asks you a question already settled by the model binding, so wrong combinations simply break runs. Second, and worse, it makes saved intakes rot.

Seeing what was actually used

Because the engine makes these choices, it also records them. A finished run carries the resolved intake — defaults filled in — and the artifact records the mechanism chosen, for instance transparencyMechanism: "native" versus "post-process". If you need to know why two runs of the same workflow behaved differently, that is where to look.