{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://atlasapp.eu/schemas/generation-api.json",
  "title": "Atlas local generation API",
  "description": "Request bodies for POST /ai/v1/command. Atlas must be open with AI access enabled. Discover model controls with generation_options. Outputs are new PNG files; folders need not be registered in Atlas.",
  "oneOf": [
    { "type": "object", "additionalProperties": false, "required": ["command"], "properties": { "command": { "const": "generation_options" }, "args": { "type": "object", "additionalProperties": false } } },
    { "type": "object", "additionalProperties": false, "required": ["command"], "properties": { "command": { "const": "generation_schema" }, "args": { "type": "object", "additionalProperties": false } } },
    { "type": "object", "additionalProperties": false, "required": ["command", "args"], "properties": { "command": { "const": "start_generation" }, "args": { "$ref": "#/$defs/start" } } },
    { "type": "object", "additionalProperties": false, "required": ["command", "args"], "properties": { "command": { "const": "get_generation" }, "args": { "$ref": "#/$defs/lookup" } } },
    { "type": "object", "additionalProperties": false, "required": ["command", "args"], "properties": { "command": { "const": "retry_generation_output" }, "args": { "$ref": "#/$defs/lookup" } } }
  ],
  "$defs": {
    "lookup": {
      "type": "object", "additionalProperties": false,
      "properties": { "jobId": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "requestId": { "type": "string", "minLength": 1, "maxLength": 160 } },
      "oneOf": [{ "required": ["jobId"] }, { "required": ["requestId"] }]
    },
    "field": {
      "type": "object", "additionalProperties": false, "required": ["source", "label", "value"],
      "properties": {
        "source": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Stable field identifier. Matching identifiers update existing fields; other fields are preserved. Maximum 160 UTF-8 bytes." },
        "label": { "type": "string", "maxLength": 160, "description": "Maximum 160 UTF-8 bytes." },
        "value": { "type": "string", "maxLength": 262144, "description": "Maximum 256 KiB in UTF-8." },
        "iconId": { "type": "string", "maxLength": 80 },
        "showInSidebar": { "type": "boolean", "default": true }
      }
    },
    "reference": {
      "type": "object", "additionalProperties": false, "required": ["path"],
      "properties": {
        "path": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Absolute path to PNG, JPEG, or WebP. Atlas snapshots the file before submitting." },
        "label": { "type": "string", "minLength": 1, "maxLength": 160 },
        "role": { "enum": ["reference", "style", "character"], "default": "reference" }
      }
    },
    "start": {
      "type": "object", "additionalProperties": false,
      "required": ["requestId", "providerId", "modelId", "prompt", "output"],
      "properties": {
        "requestId": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Caller-created retry key. Reuse the same key and arguments after a lost reply. Never reuse it for a different request." },
        "providerId": { "type": "string", "minLength": 1, "maxLength": 100 },
        "modelId": { "type": "string", "minLength": 1, "maxLength": 100 },
        "prompt": { "type": "string", "minLength": 1, "maxLength": 16000 },
        "references": { "type": "array", "maxItems": 14, "default": [], "items": { "$ref": "#/$defs/reference" }, "description": "No references means generate; one or more means edit. The chosen model may have lower limits." },
        "options": {
          "type": "object", "additionalProperties": false, "default": {},
          "description": "Use only values from the chosen model's controls in generation_options. Unsupported values are rejected before generation.",
          "properties": { "resolution": { "type": "string" }, "aspectRatio": { "type": "string" }, "quality": { "type": "string" }, "background": { "type": "string" } }
        },
        "postProcessing": { "type": "array", "maxItems": 2, "uniqueItems": true, "default": [], "items": { "enum": ["remove-jpeg-artifacts", "remove-background"] }, "description": "Atlas always applies JPEG cleanup before background removal. Required models download only when this job invokes them." },
        "output": {
          "type": "object", "additionalProperties": false, "required": ["folder", "fileName"],
          "properties": {
            "folder": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "Absolute destination directory. Atlas creates it if needed, without registering it or changing the current folder." },
            "fileName": { "type": "string", "minLength": 5, "maxLength": 180, "pattern": "^[^\\\\/:*?\"<>|]+\\.[pP][nN][gG]$", "description": "Exact PNG file name. Path separators, reserved device names, and existing files are rejected. Atlas never overwrites an output." },
            "size": {
              "description": "provider preserves provider dimensions. match uses the first reference's oriented pixel dimensions. An object requests exact final dimensions, up to 40 million pixels.",
              "default": "provider",
              "oneOf": [ { "enum": ["provider", "match"] }, { "type": "object", "additionalProperties": false, "required": ["width", "height"], "properties": { "width": { "type": "integer", "minimum": 1, "maximum": 16384 }, "height": { "type": "integer", "minimum": 1, "maximum": 16384 } } } ]
            },
            "fit": { "enum": ["contain", "cover", "fill"], "default": "contain", "description": "contain pads with transparency; cover crops at the center; fill stretches. Applies only to final size." },
            "fields": { "type": "array", "maxItems": 256, "default": [], "items": { "$ref": "#/$defs/field" }, "description": "Merge into the generated PNG's Atlas fields by source identifier. This does not change library tags or the reference image's metadata." }
          }
        }
      }
    },
    "job": {
      "type": "object",
      "required": ["jobId", "requestId", "status", "stage", "outputPath", "error", "canRetryOutput"],
      "properties": {
        "jobId": { "type": "string" }, "requestId": { "type": "string" },
        "status": { "enum": ["running", "completed", "failed", "interrupted"] },
        "stage": { "enum": ["generating", "processing", "saving", "completed"] },
        "outputPath": { "type": ["string", "null"] }, "width": { "type": ["integer", "null"] }, "height": { "type": ["integer", "null"] },
        "error": { "type": ["string", "null"] }, "canRetryOutput": { "type": "boolean" },
        "createdAt": { "type": "integer" }, "finishedAt": { "type": ["integer", "null"] }
      }
    }
  }
}