---
title: "Create image generation"
method: POST
path: "/open/v1/image-generations"
tags: ["Image Generations"]
---

# Create image generation

`POST /open/v1/image-generations`

Submit an image-generation request. The caller's `prompt` is treated as a **creative brief**: Atria expands it into `size` **distinct** concept variants and renders one image per variant. `size > 1` returns real creative variety, not seed-jittered copies of the same prompt.

Treat `prompt` as a directional brief (intent, audience, mood, visual hints), not the final image-model prompt — Atria produces the per-variant prompts internally.

**Async.** Returns immediately with a `generation_id` and (initially empty) `image_ids`. Poll `GET /open/v1/image-generations/{generation_id}` to pick up image ids and track status; see that endpoint for cadence guidance.

**Brand required.** `brand_id` must reference a workspace-owned brand from `GET /open/v1/owned-brands`. The brand's logo / colors / product context grounds the brief — there is no placeholder fallback. Cross-workspace brand ids return `code=40401`.

**Idempotency.** `idempotency_key` deduplicates retries — re-submitting the same key from the same workspace returns the same `generation_id` and never produces a duplicate charge. Pick a stable UUID per attempt; reuse only to recover from a dropped response.

**Credits.** Charged at the same rate as the in-app image generation feature — trigger one image in Atria's web app to see the current per-image credit cost; `size` multiplies it. Credits are reserved on submit; per-image failures are auto-refunded.

Errors: `code=40001` when workspace context is missing from the request; `code=40401` for unknown / cross-workspace `brand_id`; `code=50001` when the upstream image-gen service is unavailable, returns an error envelope, or rejects the submit (including credit-exhaustion at the upstream layer).

## Request body

- OpenImageGenerationCreateRequest — POST /open/v1/image-generations body. The caller supplies a creative brief in `prompt`; Atria expands it into `size` distinct concept variants and renders one image per variant. `size > 1` therefore returns real creative variety, not seed-jittered copies of the same prompt.
  - `idempotency_key` string, required — Caller-supplied dedupe key. Re-submitting with the same `idempotency_key` from the same workspace returns the same `generation_id` without spawning new images. Pick a stable UUID per attempt; reuse only to retry a specific submission.
  - `reference_image_url` string — Optional URL of a reference ad image to ground the output. When omitted, generation runs as pure text-to-image from the brief alone.
  - `prompt` string, required — Creative brief / direction. Atria expands this into `size` distinct concept variants and renders one image per variant. Treat this as a directional brief, not the final image-model prompt.
  - `brand_id` string, required — Workspace-owned brand id from `GET /open/v1/owned-brands`. The brand's logo / colors / product context grounds the brief; cross-workspace brand ids return `code=40401`.
  - `aspect_ratio` 'auto_closest_fit' | '1:1' | '4:5' | '9:16' — An enumeration.
  - `size` integer — Number of distinct concept variants to generate (1-20). Each variant produces one image.
  - `language` string — Output text language. Defaults to English.
  - `logo_url` string — Override logo URL. When omitted, uses the brand's stored logo.
  - `product_image_urls` string[] — Product images to include in generation.
  - `colors` string[] — Color palette overrides (hex). Falls back to brand colors.
  - `source_ref` string — Caller's own correlation id, persisted alongside the generation for cross-system tracking. Defaults to the `idempotency_key` when omitted.

## Response `200`

Successful Response

- OpenImageGenerationResponse — Envelope for all open API responses. code=0 means success.
  - `code` integer
  - `message` string
  - `data` OpenImageGeneration — Response payload for image-generation submit + status. Flat shape for SPI consumers — `generation_id` is the opaque identifier.
    - `generation_id` string, required — Image-generation identifier; treat as opaque.
    - `status` string, required — Generation status: `pending`, `processing`, `success`, `partial_success`, `failed`.
    - `concept_ids` string[]
    - `image_ids` string[] — Empty until the request fans out into per-image tasks (typically a few seconds after submit). Poll `GET /open/v1/image-generations/{generation_id}` to pick up the ids.

## Other responses

- `400` — Invalid request — a query parameter, path parameter, or body field failed validation.

---

[API](https://skmtc.net/tryatria/apis/atria-open-api.md) · [All operations](https://skmtc.net/tryatria/apis/atria-open-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tryatria/atria-open-api/revisions/548d57b611ea/schema)