Generate an 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).
generate_image: Make one image from a prompt written as a scene in prose, in the aspect ratio of the platform it is for, optionally conditioned on up to 6 reference_keys from the media library (a logo, a product shot, an earlier image). quality "premium" is the dearer model. Returns the image as a media key with a URL; put the key in posts_create mediaKeys. SPENDS CREDIT: about $0.016 of engine cost a default call, billed with the plan's margin; budgetUsd caps it (default 2, max 10) and chargedUsd says what it cost. Needs the write scope.
From code (REST)
Bearer API key with the scope each call names (auth, OpenAPI).
POST /api/images(write scope): Generate an image (tool generate_image): {name, prompt, aspectRatio, size?, quality?, reference_keys?, budgetUsd?}.
The body
namestring, 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.promptstring, 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.aspectRatiostring, required (1:1,4:5,3:4,16:9,9:16): LinkedIn feed image: 4:5. Wide header: 16:9.sizestring (1K,2K): 1K draft, 2K final.qualitystring (standard,premium): standard = the default model (default). premium = the fidelity escalation, several times the price.reference_keysarray: 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.budgetUsdnumber: The most this call may spend, in USD (default 2, max 10). Held while the tool runs, released after.
From a terminal (CLI)
shapeless tools run generate_image --input '<json>'(tools show generate_imageprints the schema)
Example
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
More in Media
Generate AI video · Edit a video · Record a product demo · Render a carousel · Render a thumbnail · Turn text into speech · Make subtitle files · Call any agent tool
