stability-ai-image

What it does

Operates Stability AI image generation, image-to-image, edit, control, background, and upscale APIs safely and reproducibly. Use when selecting or calling Stable Image Ultra, Core, Stable Diffusion 3.5, v2beta image edit/control services, or Stability open-weight image models; when debugging schemas, moderation, rate limits, cost, lifecycle, licenses, privacy, provenance, or migrations; and when planning production QA for Stability-generated images.

How it works

• Route the job before writing a prompt: choose between hosted Platform API or open weights; do not imply downloadable weights for Core or all microservices; match intent to a single operation; confirm output size, input constraints, cost, and synchronous/asynchronous behavior; verify rights/privacy; generate a small approved sample and record endpoint, parameters, seed, request ID, input/output hashes, cost estimate, and QA disposition.
• Use the Current hosted surface: REST v2beta is primary; stability mentions legacy surfaces for maintenance only; follow the API reference for endpoints and parameters.
• For each operation (Generate, Edit, Control, Upscale) use the specific endpoints, required fields, optional fields, and known constraints described; apply documented behavior for outputs, pricing, and limits.
• Authentication and headers: use base URL https://api.stability.ai; send Authorization: Bearer <STABILITY_API_KEY>, Accept: image/*; use multipart/form-data for image POSTs; include optional diagnostic headers; handle responses (image bytes or JSON with base64) and extract id for asynchronous polls when applicable.
• Synchronous vs asynchronous: most calls return synchronous HTTP 200 with image or JSON; Creative Upscale and Replace Background and Relight are asynchronous; poll GET /v2beta/results/{id} after POST; wait at least 10 seconds between polls; download results and retain for 24 hours.
• Example client: provided Python snippet demonstrates constructing requests, handling headers, and computing verification artifacts like seeds and IDs.

When to use it

• Triggered when selecting the appropriate Stability AI image surface (Ultra, Core, SD3, or open-weight models) and when performing edits, controls, or upscaling.
• Use during debugging of schemas, moderation, rate limits, costs, lifecycle, licenses, privacy, provenance, or migrations.
• Plan production QA for Stability-generated images and verifying provenance and policy disposition.

What it can touch

• Endpoints for Stable Image Ultra, Core, SD3, and edit/control/upscale services as listed (no explicit tool invocation names beyond REST endpoints and HTTP behaviors are included in this description).

Caveats

• Volatile API facts verified 2026-07-09; re-check API reference, pricing, and release notes before committing spend or shipping long-lived integration.
• Documentation inconsistencies exist (e.g., SD3.5 variants and pricing vs. endpoints); validate with live calls in target accounts before batching.
• Some aspects require careful QA logging (endpoint, parameters, seed, request ID, input/output hashes, cost, and policy/QA disposition) and proper handling of asynchronous results as documented.