JobRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/imagestep-dev/json-schema/imagestep-dev-job-request-schema.json",
  "title": "JobRequest",
  "description": "What to run and on what: one of `op`, `presetId` or `steps` (or a raw `type`), the inputs, and where the outputs go. The same body prices it with `?dryRun=true`.",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/imagestep-dev-openapi.json#/components/schemas/JobRequest",
  "type": "object",
  "properties": {
    "op": {
      "type": "string",
      "description": "An op name — one entry of GET /api/v1/ops, the catalogue every client enumerates. When set, `type` / `presetId` / `preset` are derived from it and `parameters` carries the op's parameters; the dry run prices it like any job."
    },
    "variants": {
      "type": "array",
      "description": "Run the op once per entry, producing one asset each — the whole set of social sizes from one call. Each entry is {name, parameters}; the parameters are merged over the top-level ones, and each name must be distinct (it is added to the output's name). Deterministic ops only — beside an AI op, `render_template` or a preset it is `400 invalid_param`; at most 20.",
      "items": {
        "type": "object",
        "additionalProperties": {}
      }
    },
    "type": {
      "type": "string",
      "description": "Job type. `chain` is what several segments run as — a preset's or inline `steps` — and is derived from them; asked for on its own it is refused.",
      "enum": [
        "ai-generate",
        "ai-edit",
        "parse",
        "process",
        "render",
        "chain"
      ]
    },
    "templateId": {
      "type": "string",
      "description": "render_template: the template to render — an id, or `id@version` to pin one version. May also be given as `parameters.templateId`."
    },
    "items": {
      "type": "array",
      "description": "render_template: one object of template variables per output image (≤ 500). May also be given as `parameters.items`.",
      "items": {
        "type": "object",
        "additionalProperties": {}
      },
      "maxItems": 500,
      "minItems": 0
    },
    "assetIds": {
      "type": "array",
      "description": "Your assets to run on — one item per id, times the `variants`. Required unless the op reads no image (`requiresAssets: false` in GET /api/v1/ops) or the job is a render. Every id must be yours: one that is not is `404 asset_not_found`, before anything is created.",
      "items": {
        "type": "string"
      },
      "maxItems": 10000,
      "minItems": 0
    },
    "imageCount": {
      "type": "integer",
      "format": "int32",
      "description": "Dry run only (`?dryRun=true`): images you have not stored yet, priced as that many more `assetIds` — one item each, times the `variants` — so the price can be asked before anything is uploaded. Beside `assetIds` it adds to them, and those are still checked. A submit needs the images themselves as `assetIds`: without `dryRun`, or on a job that reads no image (a render), it is `400 invalid_param`. At most 10000 together with `assetIds`.",
      "maximum": 10000,
      "minimum": 1
    },
    "wait": {
      "type": "integer",
      "format": "int32",
      "description": "Hold the response until the job is terminal, for at most this many seconds — capped at 60 (a larger value is clamped, not refused). A job of ONE item only; on a batch it is ignored and the handle comes back at once. Terminal inside the window → 200 with the finished job; still running → 202 with the same handle, and GET /api/v1/jobs/{id}?wait= waits again. Ignored on a dry run."
    },
    "retentionDays": {
      "type": "integer",
      "format": "int32",
      "description": "Keep the assets this job makes — and its own record — for this many days instead of your plan's retention: shorter only. More than the plan keeps is kept for the plan's time, not refused; the assets' `expiresAt` says what was stamped. Absent: the plan's retention.",
      "minimum": 1
    },
    "count": {
      "type": "integer",
      "format": "int32",
      "description": "A job with no `assetIds` that makes images from a prompt: how many to make, one item each. 1 when absent.",
      "maximum": 10,
      "minimum": 1
    },
    "presetId": {
      "type": "string",
      "description": "A saved preset to run: its slug or id, or `slug@version` / `id@version` to pin one version (GET /api/v1/presets). The preset decides the job type; `model` / `prompt` / `parameters` override its ONE AI step, and are refused by a preset that has none or several."
    },
    "steps": {
      "type": "array",
      "description": "An inline chain: the same steps a preset stores (each `{op, model?, prompt?, parameters?}` or `{operation, params}`), checked as a preset's are and run once without saving one. Sent instead of `op` or `presetId`; `model`, `prompt` and `parameters` go on the step. The job records them.",
      "items": {
        "$ref": "#/$defs/PresetStep"
      }
    },
    "subjects": {
      "type": "array",
      "description": "With `steps` only: the subjects a preset stores — reference images plus the locked words, applied to every `generate` / `edit` step, with `{{subject.<name>}}` in a prompt expanding to the descriptor. Checked as a preset's are (your own DONE assets, at most 4 subjects, and a generate or edit step to read them). The job records them.",
      "items": {
        "$ref": "#/$defs/Subject"
      }
    },
    "model": {
      "type": "string",
      "description": "The model an AI op runs on — an id from GET /api/v1/ai-models whose `categories` include the op's `modelCategory`; any other is `400 invalid_param` with the ones that fit in `details.allowed`. Absent, the op's `defaultModel`. With a preset it overrides the preset's one AI step."
    },
    "prompt": {
      "type": "string",
      "description": "The prompt of an AI op that takes one — required where the op's entry says `requiresPrompt`. With a preset it overrides the one AI step's prompt, and `{{subject.<name>}}` in it expands to that subject's descriptor."
    },
    "parameters": {
      "type": "object",
      "additionalProperties": {},
      "description": "The op's parameters. A deterministic op's are checked against its `params` in GET /api/v1/ops, and one outside them is `400 invalid_param` naming it; an AI op's go to its model (`parameters` in GET /api/v1/ai-models). With a preset they replace its one AI step's parameters."
    },
    "collection": {
      "type": "string",
      "description": "Collection to put the output assets in (optional; at most 200 characters, and names starting with job: are reserved). Without one, an output made from an asset is in that asset's collection."
    },
    "preset": {
      "$ref": "#/$defs/PipelineData",
      "description": "A raw processing pipeline — registry steps, run as one pass. What an op translates into; prefer `op`, or `steps` for several."
    }
  },
  "$defs": {
    "PipelineData": {
      "type": "object",
      "description": "An inline processing pipeline: a name and the registry steps a process job runs.",
      "properties": {
        "name": {
          "type": "string"
        },
        "pipeline": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/PipelineStep"
          }
        }
      }
    },
    "PipelineStep": {
      "type": "object",
      "properties": {
        "operation": {
          "type": "string"
        },
        "params": {
          "type": "object",
          "description": "The registry step's arguments"
        },
        "disabled": {
          "type": "boolean"
        }
      }
    },
    "PresetStep": {
      "type": "object",
      "description": "A preset step: either an L1 op from GET /api/v1/ops — {op, model?, prompt?, parameters?} — or a processing-registry step — {operation, params} — for what no op covers. Never both.",
      "properties": {
        "op": {
          "type": "string",
          "description": "An op from GET /api/v1/ops (kind ai or deterministic)."
        },
        "model": {
          "type": "string",
          "description": "AI steps: the model; the op's default when absent."
        },
        "prompt": {
          "type": "string",
          "description": "AI steps: the prompt. {{subject.<name>}} expands to that subject's descriptor."
        },
        "parameters": {
          "type": "object",
          "additionalProperties": {},
          "description": "The op's parameters. A deterministic op's are checked against its catalogue contract when the steps are written, and so are `analyze`'s bounds; an AI image op's go to the model as sent."
        },
        "operation": {
          "type": "string",
          "description": "A processing-registry key (deterministic only), for steps no op covers."
        },
        "params": {
          "type": "object",
          "description": "That registry step's arguments."
        }
      }
    },
    "Subject": {
      "type": "object",
      "description": "A recurring character, product or location: reference images plus the locked words for it.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Lowercase handle (`[a-z0-9][a-z0-9_-]{0,39}`, unique among the subjects), referenced in a prompt as {{subject.<name>}}."
        },
        "referenceAssetIds": {
          "type": "array",
          "description": "Your own DONE asset ids showing this subject. They pin the geometry.",
          "items": {
            "type": "string"
          }
        },
        "descriptor": {
          "type": "string",
          "description": "The locked description — colour, material, markings — at most 300 characters. Text pins what an image cannot show."
        }
      }
    }
  }
}