Skip to content
ShapelessAI← Back
Media

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.

View as Markdown

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

  • 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 string, required (1:1, 4:5, 3:4, 16:9, 9:16): LinkedIn feed image: 4:5. Wide header: 16:9.
  • size string (1K, 2K): 1K draft, 2K final.
  • quality string (standard, premium): standard = the default model (default). premium = the fidelity escalation, several times the price.
  • reference_keys array: 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.

From a terminal (CLI)

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

Example

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

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

Every capability · Docs · /llms.txt