POST /images

Generate a standalone on-brand image from a text prompt.

Start an asynchronous image generation from a text prompt. Returns an imageGenerationId to poll for the image URL and metadata.

Create async image generation

post

Creates an asynchronous image generation job that produces one standalone on-brand image. Returns an image generation ID that can be used to poll for status. If themeId is provided but does not exist or is not accessible to your workspace, the request fails with 400.

Authorizations

X-API-KEYstringRequired

API key for authentication

Body

typestring · enumOptional

Visual style of the generated images. Defaults to "illustration". Skipped when referenceImages are present — references take precedence and style comes from the prompt.

Default: illustrationExample: illustrationPossible values:

sizePresetstring · enumOptional

Output size preset (sets the aspect ratio; exact pixel dimensions are model-determined). Defaults to "social-square" (1:1).

Default: social-squareExample: social-squarePossible values:

promptstring · max: 5000Required

Description of the image to generate. Background treatments ("on white", "contained in a circle") go here.

Example: illustration of a team running payroll accurately and on time, on whitePattern: \S

themeIdstringOptional

Theme to brand the images with. Defaults to the workspace default theme. Applied for all types except "scene", whose curated style ignores theme colors (a theme_ignored_for_type warning is returned if you supply themeId for scene). Also ignored when referenceImages are present — references drive the look.

Example: abc123xyz

Responses

200

Image generation job created successfully

application/json

imageGenerationIdstringRequired

Unique identifier for the image generation job. Poll GET /v1.0/images/{id} with this id until status is "completed" or "failed".

Example: abc123xyz

400

Invalid request parameters

401

Invalid or missing API key

402

Insufficient credits

403

Access denied or feature not available

404

Not found

post/v1.0/images

POST /v1.0/images HTTP/1.1
Host: public-api.gamma.app
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 235

{
  "type": "illustration",
  "sizePreset": "social-square",
  "referenceImages": [
    {
      "url": "https://example.com/mascot.png",
      "role": "subject"
    }
  ],
  "prompt": "illustration of a team running payroll accurately and on time, on white",
  "themeId": "abc123xyz"
}

{
  "imageGenerationId": "abc123xyz",
  "warnings": [
    {
      "code": "no_brand_theme_applied",
      "message": "No brand theme found; a standard theme was used."
    }
  ]
}

Poll GET /images/{id} with the returned imageGenerationId until status is completed or failed. If themeId does not exist or is not accessible to your workspace, the request fails with 400.

Related

• GET /images/{id} to poll for the image URL and savedMediaId
• Poll for results for polling patterns and rate limit guidance
• Warnings for image-generation warning codes returned in the response