image-generation

name	image-generation
description	Generate images from text prompts (and optionally edit/remix input images). Use when the user asks to create, generate, draw, render, or edit an image, illustration, logo, icon, diagram, or photo.

Image Generation

Generate images via Letta's hosted endpoint POST /v1/images/generations. The API usually returns base64 image bytes, but some providers return signed image URLs; save either form to a local image file before replying.

Example

Generate the image, save it locally, then show it inline:

base_url="${LETTA_BASE_URL%/}"

curl -sS -X POST "$base_url/v1/images/generations" \
  -H "Authorization: Bearer $LETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"gemini","prompt":"a friendly robot mascot waving, flat vector logo, mint green background","n":1}' \
  > image-response.json

python3 - <<'PY'
import base64, json, urllib.request

with open("image-response.json") as f:
    response = json.load(f)

image = response["images"][0]
if image.get("b64_json"):
    data = base64.b64decode(image["b64_json"])
else:
    data = urllib.request.urlopen(image["url"]).read()

with open("robot-mascot.png", "wb") as f:
    f.write(data)

print("saved robot-mascot.png; credits:", response["billing"]["credits_charged"])
PY

In Bash tools launched by Letta Code, use the runtime-provided LETTA_BASE_URL and LETTA_API_KEY together for Letta API calls. Build URLs relative to ${LETTA_BASE_URL%/} and send Authorization: Bearer $LETTA_API_KEY. Do not hardcode https://api.letta.com: Desktop and remote runtimes may provide a proxy base URL, and the credential may only be valid through that URL. If either variable is missing, the user needs to authenticate with Letta Cloud (or provide a Letta API key); do not ask for an OpenAI/Gemini provider key. This endpoint also does not use /connect BYOK providers — the only provider values supported here are flux, gemini, and openai.

Then show the image to the user by embedding the saved file in your reply:

Here's the mascot:

![a friendly robot mascot waving, flat vector logo](./robot-mascot.png)

The Letta Code UI renders local file paths in markdown image tags, so the image appears inline. Always display generated images this way — don't just report the path, and never paste the raw base64 / a data: URI. The markdown path must match where you saved the file. For n > 1, save each image to its own file and embed each on its own line. Also tell the user the credits_charged.

Request body

Field	Type	Notes
provider	"flux" | "gemini" | "openai"	Required.
prompt	string	Required, 1–32000 chars.
model	string	Optional; defaults per provider (below).
n	int 1–4	Optional, default 1. Request variations in one call.
size	string	Optional, e.g. "1024x1024" (OpenAI).
quality	low|medium|high|auto	Optional (OpenAI; higher = more credits).
output_format	png|jpeg|webp	Optional (OpenAI).
input_images	string[] (max 14)	Optional. Base64 data URLs for edit/remix.
seed	int	Optional.

Provider	Default model	Use for
flux	flux-2-pro	Default for normal text-to-image. High-quality general image generation; commonly returns signed URLs.
gemini	gemini-3-pro-image	Strong prompt adherence, image editing/remix.
openai	gpt-image-2	Photoreal output, explicit size/quality/output_format.

Default to flux for normal text-to-image requests. Use gemini when the user provides input images or wants image editing/remix. Use openai when the user wants photoreal output or a specific size/quality.

Response

{
  "provider": "gemini",
  "model": "gemini-3-pro-image",
  "images": [{ "b64_json": "<base64>", "mime_type": "image/png" }],
  "billing": { "credits_charged": 12, "...": "..." }
}

Each images[] entry has either b64_json or url, plus mime_type. Gemini always returns b64_json. Flux commonly returns a signed url; download it to your local image file immediately because signed URLs expire. If OpenAI returns a url, download that URL instead of base64-decoding.

Editing / remixing images

Pass source images in input_images as base64 data URLs (data:<mime>;base64,<data>) and describe the edit in prompt. Gemini handles multi-image edits well. To build a data URL from a local file:

DATA_URL="data:image/png;base64,$(base64 < input.png | tr -d '\n')"

Notes

• Billing: every success charges credits; don't loop needlessly, and report credits_charged.
• Errors: 402 = insufficient credits (credits_required in body); 400/500 return { "message": "..." } — surface it to the user.
• Only flux, gemini, and openai are supported here.