Workflow Structure

Anatomy of a Workflow

A workflow consists of:

Name: set when you create it; new workflows are private
Versions: each version holds a complete definition
Definition: inputs, steps and optional named outputs

{
  "name": "Text to Image Generator",
  "definition": {
    "input_schema": { ... },
    "steps": [ ... ],
    "metadata": {
      "output_mapping": { ... }
    }
  }
}

Definition Fields

Field	Type	Required	Description
`steps`	array	Yes	Steps to run, top to bottom
`input_schema`	object	No	Workflow inputs (see Input Schema)
`metadata.output_mapping`	object	No	Named outputs returned as `workflow_output`, e.g. `{"image": "$.generate_image.primary"}`
`version`	string	No	Name of the first version when creating a workflow (default `"v1"`)

Retries and timeouts are set per step, not for the whole workflow.

Steps

Each step defines an operation in the workflow. Steps can be model invocations, HTTP requests, Python functions, parallel branches, conditional logic, or simple pass-through operations.

{
  "id": "generate_image",
  "type": "model",
  "model": "nano-banana-2-text-to-image",
  "params": {
    "prompt": "$.inputs.prompt",
    "aspect_ratio": "16:9"
  }
}

Base Step Fields

All step types share these fields:

Field	Type	Required	Description
`id`	string	Yes	Unique identifier within the workflow
`type`	string	Yes	Step type: `model`, `http`, `python`, `parallel`, `choice`, or `pass`
`continue_on_error`	boolean	No	Continue workflow execution even if this step fails
`timeout_seconds`	integer	No	Maximum execution time for this step
`retry`	object	No	Step-level retry configuration

Retry Configuration

{
  "retry": {
    "max_attempts": 3,
    "backoff_multiplier": 2,
    "initial_delay_seconds": 1,
    "retry_on": ["timeout", "server_error"]
  }
}

Field	Type	Default	Description
`max_attempts`	integer	`3`	Maximum number of attempts
`backoff_multiplier`	number	`2`	Multiplier for the delay between attempts
`initial_delay_seconds`	number	`1`	Delay before the second attempt
`retry_on`	string[]	`["server_error"]`	Failure types that trigger a retry: `timeout`, `server_error`

Step Types

Type	Description
`model`	Invokes an AI model via each::api
`http`	Makes an HTTP request to an external URL
`python`	Executes a Python function
`parallel`	Executes multiple branches concurrently
`choice`	Evaluates a condition and routes to the matching branch
`pass`	Passes input through without processing, optionally injecting a result

Model Steps

Invoke an AI model from the each::api catalog.

{
  "id": "restyle",
  "type": "model",
  "model": "nano-banana-2-edit",
  "params": {
    "prompt": "Restyle this photo as $.inputs.style. Keep the person's face unchanged.",
    "image_urls": ["$.inputs.photo"]
  },
  "fallback": {
    "enabled": true,
    "model": "gpt-image-v2-edit",
    "params": {
      "prompt": "Restyle this photo as $.inputs.style. Keep the person's face unchanged.",
      "image_urls": ["$.inputs.photo"]
    }
  }
}

Field	Type	Required	Description
`model`	string	Yes	AI model slug; read its inputs with `GET /v1/models/{slug}`
`params`	object	No	Model parameters; supports `$.` references
`fallback`	object	No	Fallback configuration

HTTP Steps

Make HTTP requests to external APIs or services.

{
  "id": "call_api",
  "type": "http",
  "url": "https://api.example.com/process",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "data": "{{step1.primary}}"
  },
  "auth": {
    "type": "bearer",
    "token": "{{inputs.api_token}}"
  },
  "timeout": 30000
}

Field	Type	Required	Default	Description
`url`	string	Yes	`-`	Request URL (supports template variables)
`method`	string	No	`GET`	HTTP method: `GET`, `POST`, `PUT`, `DELETE`, `PATCH`
`headers`	object	No	`-`	Request headers
`query_params`	object	No	`-`	URL query parameters
`body`	any	No	`-`	Request body
`auth`	object	No	`-`	Authentication configuration
`timeout`	integer	No	`-`	Request timeout in milliseconds
`follow_redirects`	boolean	No	`-`	Follow HTTP redirects
`validate_ssl`	boolean	No	`-`	Validate SSL certificates

Auth Configuration

Field	Type	Description
`type`	string	Auth type: `basic`, `bearer`, or `api_key`
`username`	string	For `basic` auth
`password`	string	For `basic` auth
`token`	string	For `bearer` auth

Python Steps

Execute Python code within the workflow.

{
  "id": "transform_data",
  "type": "python",
  "code": "result = inputs['text'].upper()",
  "inputs": {
    "text": "{{step1.primary}}"
  }
}

Field	Type	Required	Description
`code`	string	Yes	Python code to execute
`inputs`	object	No	Input variables available in the code (supports template variables)

Parallel Steps (Branching)

Use type: "parallel" to run multiple branches concurrently. Each branch contains its own sequence of steps that execute independently.

{
  "id": "step1",
  "type": "parallel",
  "branches": [
    {
      "name": "Branch 1",
      "steps": [
        {
          "id": "step1_branch_0",
          "type": "model",
          "model": "kling-v3-pro-image-to-video",
          "params": {
            "prompt": "A bee collecting nectar, wings vibrating",
            "start_image_url": "https://example.com/bee.png",
            "duration": "5"
          }
        }
      ]
    },
    {
      "name": "Branch 2",
      "steps": [
        {
          "id": "step1_branch_1",
          "type": "model",
          "model": "nano-banana-2-edit",
          "params": {
            "prompt": "Transform into Cubism style",
            "image_urls": ["https://example.com/scene.png"],
            "aspect_ratio": "16:9"
          }
        }
      ]
    },
    {
      "name": "Branch 3",
      "steps": [
        {
          "id": "step1_branch_2",
          "type": "model",
          "model": "nano-banana-2-text-to-image",
          "params": {
            "prompt": "Ultra realistic photo of a modern summer store",
            "aspect_ratio": "16:9"
          }
        }
      ]
    }
  ]
}

Branch Fields

Field	Type	Required	Description
`name`	string	No	Label for readers; the engine names branches by position
`steps`	array	Yes	Steps to run in order within this branch

All branches kick off at the same time and run independently. The parallel step wraps up once every branch finishes.

Choice Steps (Conditional Logic)

Use type: "choice" to route execution based on a condition. The workflow evaluates the condition and picks either the condition_met_branch or the default_branch.

{
  "id": "portrait",
  "type": "choice",
  "condition": {
    "expression": "$.subject.primary.choices[0].message.content",
    "operator": "string_matches",
    "value": "*PET*"
  },
  "condition_met_branch": {
    "name": "pet",
    "steps": [
      {
        "id": "pet_portrait",
        "type": "model",
        "model": "nano-banana-2-edit",
        "params": {
          "prompt": "A royal oil-painting portrait of this animal wearing a small crown.",
          "image_urls": ["$.inputs.photo"]
        }
      }
    ]
  },
  "default_branch": {
    "name": "person",
    "steps": [
      {
        "id": "person_portrait",
        "type": "model",
        "model": "nano-banana-2-edit",
        "params": {
          "prompt": "A royal oil-painting portrait of this person wearing a crown. Keep their face unchanged.",
          "image_urls": ["$.inputs.photo"]
        }
      }
    ]
  }
}

Here subject is an earlier eachlabs-llm-router step that answers PET or PERSON. After the choice, $.portrait.primary is the image from whichever branch ran. The full workflow is example 7 on the overview.

Condition Types

Conditions can be simple (single comparison) or logical (combining multiple conditions).

Simple Condition

Compares a single expression against a value:

{
  "expression": "$.step1.primary",
  "operator": "string_matches",
  "value": "*.mp4"
}

Field	Type	Required	Description
`expression`	string	Yes	One `$.` reference to evaluate (e.g., `$.step1.primary`, `$.inputs.email`)
`operator`	string	Yes	Comparison operator (see table below)
`value`	any	Yes, except existence operators	Value to compare against

Logical Conditions

Combine multiple simple conditions using and, or, or not:

{
  "and": [
    {"expression": "$.step1.primary", "operator": "string_matches", "value": "*.png"},
    {"expression": "$.inputs.upscale", "operator": "equals", "value": true}
  ]
}

{
  "or": [
    {"expression": "$.step1.primary", "operator": "string_matches", "value": "*.mp4"},
    {"expression": "$.step1.primary", "operator": "string_matches", "value": "*.webm"}
  ]
}

{
  "not": {
    "expression": "$.inputs.style",
    "operator": "equals",
    "value": ""
  }
}

Condition Operators

Comparison Operators

Operator	Description	Example
`equals`	Equal, including type: `5` does not equal `"5"`	`$.inputs.count` equals `5`
`not_equals`	Not equal, including type	`$.inputs.format` not equals `"raw"`
`greater_than`	Numeric greater than	`$.step1.output.score` greater than `0.8`
`less_than`	Numeric less than	`$.step1.output.score` less than `0.5`
`greater_than_or_equal`	Numeric greater than or equal	`$.inputs.count` >= `1`
`less_than_or_equal`	Numeric less than or equal	`$.inputs.count` <= `10`

String Operators

Operator	Description	Example
`string_equals`	Explicit string equality	`$.inputs.format` string equals `"png"`
`string_matches`	Pattern with `` wildcards; without `` it must match exactly	`$.step1.primary` matches `"*.mp4"`

To test one of several values, combine equals conditions with or.

Existence Operators

Operator	Description	Example
`exists`	The field is present (even if its value is `null`)	`$.step1.output.url` exists
`is_not_null`	Same as `exists`	`$.step1.primary` is not null
`is_null`	The field is present and `null`; fails the run if the field is missing	`$.step1.output.error` is null
`not_exists`	Same as `is_null`	`$.step1.output.error` not exists

Existence operators (exists, not_exists, is_null, is_not_null) do not require a value field in the condition.

Choice Branch Fields

Field	Type	Required	Description
`name`	string	No	Branch name, returned as `selected`; the two branches need different names
`steps`	array	Yes	Steps to run in this branch (at least one)

Pass Steps

A step that does no processing and returns a fixed value.

{
  "id": "static_config",
  "type": "pass",
  "result": {
    "style": "cinematic",
    "quality": "high"
  }
}

Field	Type	Required	Description
`result`	any	No	Fixed value to return; `$.` references inside it are not resolved

Later steps read its fields directly, for example $.static_config.style.

Input Schema

List the inputs under properties. Each input takes:

Field	Type	Description
`type`	string	`string`, `number`, `boolean`, `image`, `video`, `voice` (audio), `file` or `json_array`; describes the input, the engine does not convert values
`required`	boolean	`true` rejects a run that leaves the input out or empty
`default_value`	any	Used when the caller leaves the input out
`description`	string	Optional help text

{
  "input_schema": {
    "properties": {
      "photo": { "type": "image", "required": true, "description": "Photo of the person" },
      "style": { "type": "string", "required": false, "default_value": "a 1990s film photo" },
      "num_images": { "type": "number", "required": false, "default_value": 1 }
    }
  }
}

A run fails if a step references an input that was left out and has no default_value. Files are passed as public URLs; upload your own with each::storage.

Execution Flow

Steps run sequentially by default. Each step’s output is available to subsequent steps via parameter references. Parallel and choice steps let you add branching and conditional logic into the mix.

Sequential:    inputs → step1 → step2 → step3 → output

Parallel:      inputs → ┬─ Branch 1 ─┐
                        ├─ Branch 2 ─┤→ next step
                        └─ Branch 3 ─┘

Conditional:   inputs → step1 → choice ─┬─ condition met → step A
                                         └─ default       → step B

Step Outputs

Each completed step produces a StepOutput:

{
  "step_id": "generate_image",
  "kind": "model",
  "status": "completed",
  "started_at": "2025-01-15T10:00:00Z",
  "completed_at": "2025-01-15T10:00:12Z",
  "output": ["https://storage.example.com/image1.png"],
  "primary": "https://storage.example.com/image1.png",
  "metadata": {
    "model": "flux-1-1-pro",
    "version": "0.0.1",
    "prediction_id": "pred-123",
    "elapsed_seconds": 12.5,
    "params": { ... }
  }
}

Field	Description
`kind`	Step type: `model`, `http`, `python`, `parallel`, `choice`, `pass`
`status`	Execution status: `running`, `completed`, `failed`, `cancelled`, `queued`, `skipped`
`output`	Full step output (string, array, or object)
`primary`	First/main result for quick access
`metadata`	Step configuration and runtime info
`error`	Error message if the step failed
`error_cause`	Detailed error cause

Choice Step Output

A choice step reports the branch that ran in selected, and its output and primary are that branch’s result:

{
  "kind": "choice",
  "status": "completed",
  "selected": "pet",
  "output": "https://cdn-us.eachlabs.ai/uploads/450d34d7.png",
  "primary": "https://cdn-us.eachlabs.ai/uploads/450d34d7.png"
}

Fallback Output

When a fallback kicks in, a separate step output appears with a _fallback suffix:

{
  "step_id": "step1_fallback",
  "status": "completed",
  "fallback": {
    "fallback_from_step": "step1",
    "reason": "primary_failed"
  },
  "primary": "https://cdn-us.eachlabs.ai/uploads/7c1e.png",
  "metadata": { "model": "gpt-image-v2-edit" }
}

Fallback reasons: primary_failed (the primary model failed and the fallback ran) or not_triggered (the primary model succeeded; the fallback entry has status skipped). Later steps that reference $.step1.primary receive the fallback’s result when it ran.

Overview

Concepts

API Reference

OpenAPI Reference

Webhooks

Examples

Anatomy of a Workflow

Definition Fields

Steps

Base Step Fields

Retry Configuration

Step Types

Model Steps

HTTP Steps

Auth Configuration

Python Steps

Parallel Steps (Branching)

Branch Fields

Choice Steps (Conditional Logic)

Condition Types

Simple Condition

Logical Conditions

Condition Operators

Comparison Operators

String Operators

Existence Operators

Choice Branch Fields

Pass Steps

Input Schema

Execution Flow

Step Outputs

Choice Step Output

Fallback Output

​Anatomy of a Workflow

​Definition Fields

​Steps

​Base Step Fields

​Retry Configuration

​Step Types

​Model Steps

​HTTP Steps

​Auth Configuration

​Python Steps

​Parallel Steps (Branching)

​Branch Fields

​Choice Steps (Conditional Logic)

​Condition Types

​Simple Condition

​Logical Conditions

​Condition Operators

​Comparison Operators

​String Operators

​Existence Operators

​Choice Branch Fields

​Pass Steps

​Input Schema

​Execution Flow

​Step Outputs

​Choice Step Output

​Fallback Output

Anatomy of a Workflow

Definition Fields

Steps

Base Step Fields

Retry Configuration

Step Types

Model Steps

HTTP Steps

Auth Configuration

Python Steps

Parallel Steps (Branching)

Branch Fields

Choice Steps (Conditional Logic)

Condition Types

Simple Condition

Logical Conditions

Condition Operators

Comparison Operators

String Operators

Existence Operators

Choice Branch Fields

Pass Steps

Input Schema

Execution Flow

Step Outputs

Choice Step Output

Fallback Output