---
title: "Generate an image (tool generate_image): {name, prompt, aspectRatio, size?, quality?, reference_keys?, budgetUsd?}."
method: POST
path: "/api/images"
---

# Generate an image (tool generate_image): {name, prompt, aspectRatio, size?, quality?, reference_keys?, budgetUsd?}.

`POST /api/images`

## Request

- Base URL: `https://shapelessai.com`
- URL: `https://shapelessai.com/api/images`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shapelessai.com/api/auth/mcp/authorize`, token URL `https://shapelessai.com/api/auth/mcp/token`, scopes: `write`)

## Request body

- object
  - `name` string, required: A 2-6 word filename for this image, the way you would describe it to a colleague - e.g. "founder desk golden hour". Becomes the file the user sees in their Assets.
  - `prompt` string, required: The full scene as 2-5 sentences of flowing prose, directing medium, subject, setting, light, and composition — YES "A photorealistic overhead shot of a cluttered founder desk at golden hour, one glowing laptop as the focal point, deep negative space on the right", NOT "desk, laptop, startup, 4k, trending, professional". When reference_keys are given, also say what each referenced object does in the scene.
  - `aspectRatio` '1:1' | '4:5' | '3:4' | '16:9' | '9:16', required: LinkedIn feed image: 4:5. Wide header: 16:9.
  - `size` '1K' | '2K': 1K draft, 2K final.
  - `quality` 'standard' | 'premium': standard = the default model (default). premium = the fidelity escalation, several times the price.
  - `reference_keys` string[]: Up to 6 media keys to condition on: brand-asset keys from the digest, mediaKeys of earlier generated images, or chat-upload keys. Omit for a purely imagined scene.
  - `budgetUsd` number: The most this call may spend, in USD (default 2, max 10). Held while the tool runs, released after.

## Response `200`

OK

- ToolResult
  - `tool` string, required
  - `output` unknown, required
  - `media` object[], required: Every media key the output names, with the URL that streams it (read scope). Put a key on a post's mediaKeys.
    - `key` string
    - `url` string, uri
  - `chargedUsd` number, required

## Other responses

- `400`: The input does not match the tool's schema; the message names the field.
- `401`: No credential, or not valid.
- `402`: Not enough credit to hold budgetUsd, or the call costs more than budgetUsd.
- `403`: The key is missing the "write" scope.
- `404`: No such tool on this deployment.
- `422`: The tool refused this input; nothing was charged.
- `429`: Over the key's rate limit (600 requests an hour).
- `502`: The tool failed; nothing was charged.

---

[API](https://skmtc.dev/shapelessai/apis/shapeless-api.md) · [All operations](https://skmtc.dev/shapelessai/apis/shapeless-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shapelessai/apis/shapeless-api/revisions/fae8f701d466?raw)