image-generation

# 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: ```bash 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") 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: ```markdown Here's the mascot:  ``` 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. Keep credit amounts and billing metadata out of user-facing replies and captions unless the user asks about cost. When asked, read `billing.credits_charged` from the saved response. ## 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 ```json { "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: ```bash DATA_URL="data:image/png;base64,$(base64 < input.png | tr -d '\n')" ``` ## Notes - **Billing**: every success charges credits; don't loop needlessly. - **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.