> **Shapeless capabilities index**
> Fetch https://shapelessai.com/llms.txt to discover every page before exploring further.
> Every page also answers Markdown: append `.md` to its path, or send `Accept: text/markdown`.

# Generate an image

*Verified 2026-10-07. Source: https://shapelessai.com/capabilities/generate-image*

Make one image from a prompt, optionally steered by reference images from the media library, on the frontier image models our studio agent uses, and get it back as a media key with a URL.

Pick the aspect ratio for the platform it is going to. The key goes straight into a post's mediaKeys or a carousel. The credit is held for the call's budget and settled at what it really cost; a refusal or failure is never charged.

## Ask in plain words

- "make an image of a founder desk at dusk for LinkedIn"
- "image generation API for social posts"
- "generate a 4:5 cover image for this Instagram post"

## From an agent host (MCP)

Server: `https://shapelessai.com/mcp` ([add it to your host](https://shapelessai.com/connect)).

- `tools_run` with `{ "name": "generate_image", "input": { ... } }`: the input is the REST body below; `tools_list` prints its JSON Schema.

## From code (REST)

Bearer API key with the scope each call names ([auth](https://shapelessai.com/docs/auth), [OpenAPI](https://shapelessai.com/api/openapi.json)).

- `POST /api/images` (write scope): Generate an image (tool generate_image): {name, prompt, aspectRatio, size?, quality?, reference_keys?, budgetUsd?}.

## From a terminal (CLI)

- `shapeless tools run generate_image --input '<json>'` (`tools show generate_image` prints the schema)

## Example

```bash
curl -s https://shapelessai.com/api/images -H "Authorization: Bearer $SHAPELESS_API_KEY" -H "Content-Type: application/json" -d '{"name":"founder desk","prompt":"A quiet founder desk at dusk, one lamp, deep shadows.","aspectRatio":"4:5"}'
```

## Refusals

| Status | Meaning |
| --- | --- |
| 400 | The input does not match the tool's schema; the message names the field. |
| 402 | Not enough credit to hold budgetUsd, or the call costs more than budgetUsd. |
| 404 | No such tool on this deployment. |
| 422 | The tool refused this input; nothing was charged. |
| 502 | The tool failed; nothing was charged. |

## Where else

- [The api docs](https://shapelessai.com/docs/api) ([markdown](https://shapelessai.com/docs/api.md))