Image generation

Send a prompt and optional reference files to Atlas, then retrieve a new PNG at the exact path you requested. Atlas uses its saved provider connection and keeps its current folder, selection, and generation draft unchanged.

Start with Connect a local tool for HTTP authentication or MCP setup. All commands below use POST /ai/v1/command. With MCP, use atlas_query for discovery and job lookup, and atlas_act to start work or retry output processing.

Discover models and settings

{
  "command": "generation_options",
  "args": {}
}

Build your model picker from this response each time you open the controls. Atlas returns its local catalog and saved connection state without waiting for provider credit checks. Models from disconnected providers are excluded. Atlas refreshes provider catalogs in the background and checks the selected model again when a request starts.

Send a generation request

Create a request ID once and keep it with the target panel in your editor. Choose a model from discovery. References use absolute paths on the computer running Atlas. Atlas snapshots those files before submitting the job.

{
  "command": "start_generation",
  "args": {
    "requestId": "editor-panel-42-attempt-1",
    "providerId": "<providerId from discovery>",
    "modelId": "<model id from discovery>",
    "prompt": "Keep the layout and replace the cloudy sky with a clear sky.",
    "references": [{ "path": "C:/Artwork/panel-42.png" }],
    "output": {
      "folder": "C:/Artwork/generated",
      "fileName": "panel-42-clear-sky.png",
      "size": "match",
      "fit": "contain",
      "fields": [{
        "source": "editor.panel-id",
        "label": "Panel ID",
        "value": "42"
      }]
    }
  }
}

The paths above are examples. Use the user's actual paths, including native absolute paths on macOS or Linux. To generate without a reference, omit references and use output.size: "provider" or explicit dimensions. match needs a first reference.

Each reference uses the following fields. Its file must be PNG, JPEG, or WebP, regardless of whether it is indexed by Atlas.

Set output size and cleanup

options controls the provider request. output controls the finished file. For example, choose a model's generation resolution through options.resolution and request the original panel's exact dimensions through output.size: "match". Atlas fits the generated result to those dimensions after generation.

For explicit dimensions, use output.size: { width: 1600, height: 900 }. The file always uses PNG. contain preserves the full image and adds transparent padding. cover crops at the center. fill stretches the image.

The output folder can be outside every Atlas project. Atlas creates it if needed. It never changes or replaces the reference file. If the exact output name already exists, the request fails instead of overwriting it.

{
  "postProcessing": [
    "remove-jpeg-artifacts",
    "remove-background"
  ]
}

Atlas always applies JPEG cleanup before background removal. Required models download only when this job invokes them.

Write metadata fields

Merge into the generated PNG's Atlas fields by source identifier. This does not change library tags or the reference image's metadata. Use a stable source value for each field your tool owns. Atlas preserves other named fields in the generated PNG. Writing these fields does not add the file to an Atlas project.

Read results and recover a request

Starting returns a job receipt before generation completes. Keep your editor usable while the job runs. Query the receipt with exactly one of jobId or the original requestId. When it completes, read outputPath and put that file into the panel saved with the request ID.

{
  "command": "get_generation",
  "args": {
    "requestId": "editor-panel-42-attempt-1"
  }
}

• If a start reply is lost, resend the same request ID and arguments. Atlas returns the same receipt. Reusing the ID with different arguments is rejected.
• If cleanup or saving fails and canRetryOutput is true, call retry_generation_output with the same lookup arguments. Resolve the local problem first, for example an unwritable folder. This retry does not submit another paid generation.
• If Atlas stops during generation, the request can become interrupted. Atlas does not resend it automatically. The provider may already have processed or charged for it.
• Atlas permits up to four external jobs at once, shared with the older image-edit commands. If a start is rejected because the limit is full, wait for an active job to finish.

Request schema and compatibility

Fetch generation_schema to get the request schema from the running Atlas version. The download below is the website's copy. Atlas owns the source, and the website build checks that its copy matches. Field lists on this page derive from that same file.

The schema's $defs.job describes a job receipt. The older start_image_edit and get_image_edit commands remain available for existing clients. Use start_generation and get_generation for new tools.