Image Generation and Editing Basics
Explore how to implement image generation and editing endpoints with predictable API contracts. Understand strategies for uploading images, enforcing validation, handling errors, and ensuring robust client-server interactions in multimodal AI workflows.
Text endpoints usually return JSON, so the client can parse fields and move on. An /images endpoint breaks that pattern because the useful output is binary media, and that forces a decision about how the API represents an image artifact and how the UI verifies it received a real image.
This lesson sticks to one clean boundary. A FastAPI route accepts an instruction, optionally accepts an image and mask, and returns an image artifact in a predictable shape that a Streamlit page can display and offer as a download.
The contract has three parts. The request needs stable fields for prompt and options — a required prompt, and optional fields like model, size, and a response_format that tells the server which of three response shapes to return. The response needs a single authoritative image reference, returned as one of three variants: a signed URL (best for large images, fetched client-side), a base64 JSON payload (convenient but ~33% larger), or streamed bytes (best for very large images, no JSON envelope). Both sides need size and type constraints — content_type and size_bytes on the response, and length limits on the prompt — so failures show up early and consistently rather than surfacing as a corrupted download.
These three boundary decisions matter more than any provider parameter name. Separating generation inputs from editing inputs in the request model keeps validation errors precise and keeps optional fields from becoming ambiguous. Isolating all vendor-specific arguments inside one provider-call function keeps the FastAPI route stable even if the provider returns bytes today and URLs tomorrow. And treating the response as an artifact that must be decoded and checked before display — then passing those same bytes into the download handler — keeps the UI from re-encoding or corrupting the file.
Add editing as a second path
With generation returning a single artifact, the next pressure point is getting an input image into the request without breaking validation or observability. Two common shapes work. Multipart upload sends raw bytes as files, while base64 in JSON ...