stability-ai

## Overview

Image generation via Stability AI (SD3.5, Ultra, Core). Text-to-image, img2img, inpainting, upscale, remove-bg, search-replace. 15 artistic styles.

## When to Use This Skill

- When the user mentions "stability ai" or related topics
- When the user mentions "stable diffusion" or related topics
- When the user mentions "sd3.5" or related topics
- When the user mentions "gerar arte" or related topics
- When the user mentions "gerar ilustracao" or related topics
- When the user mentions "image to image" or related topics

## Do Not Use This Skill When

- The task is unrelated to stability ai
- A simpler, more specific tool can handle the request
- The user needs general-purpose assistance without domain expertise

## How It Works

A skill for generating artistic and photorealistic images using the Stability AI API.
**Free** with the Community License (no limit for personal use / small businesses).

## When To Use This Skill Vs Ai-Studio-Image

| Scenario | Recommended skill |
|---------|-------------------|
| Humanized photo for Instagram/social media | ai-studio-image |
| Digital art, illustration, concept art | **stability-ai** |
| Photo with a phone camera (casual realism) | ai-studio-image |
| Cinematic photorealism (8K, detailed) | **stability-ai** |
| Educational material with a professional look | ai-studio-image |
| Poster, wallpaper, book cover, game asset | **stability-ai** |
| Inpainting (edit part of an image) | **stability-ai** |
| Upscale (increase resolution) | **stability-ai** |
| Remove an image's background | **stability-ai** |
| Search & Replace (swap an object in an image) | **stability-ai** |
| Erase an element from an image | **stability-ai** |

## Quick Setup

1. Create an account at **platform.stability.ai** (free)
2. Copy the API Key from the dashboard
3. Paste it into `.env`: `STABILITY_API_KEY=sk-sua-chave-aqui`
4. `pip install -r scripts/requirements.txt`

Full details in `references/setup-guide.md`.

## 1. Operating Modes

| Command | What it does | Endpoint |
|---------|-----------|----------|
| `--mode generate` | Text to image (SD3.5) | `/generate/sd3` |
| `--mode ultra` | Premium text to image | `/generate/ultra` |
| `--mode core` | Fast text to image | `/generate/core` |
| `--mode img2img` | Image + text to a new image | `/generate/sd3` |
| `--mode upscale` | Increase resolution (conservative) | `/upscale/conservative` |
| `--mode upscale-creative` | Increase resolution with detail | `/upscale/creative` |
| `--mode remove-bg` | Remove background (transparent PNG) | `/edit/remove-background` |
| `--mode inpaint` | Edit part of the image (mask) | `/edit/inpaint` |
| `--mode search-replace` | Swap an object by description | `/edit/search-and-replace` |
| `--mode erase` | Erase part of the image | `/edit/erase` |

## 2. Usage Examples

```bash

## Basic Generation (Sd 3.5 Large)

python scripts/generate.py --prompt "a serene mountain landscape at sunset" --mode generate

## Maximum Quality (Ultra)

python scripts/generate.py --prompt "cinematic portrait, dramatic lighting" --mode ultra --aspect-ratio 16:9

## Fast For Iteration (Core)

python scripts/generate.py --prompt "cute cat ninja" --mode core --style anime

## Image-To-Image

python scripts/generate.py --prompt "watercolor style" --mode img2img --image foto.jpg --strength 0.7

## Conservative Upscale

python scripts/generate.py --prompt "landscape photo" --mode upscale --image foto_pequena.jpg

## Remove Background

python scripts/generate.py --mode remove-bg --image produto.jpg

## Inpainting With A Mask

python scripts/generate.py --prompt "red roses" --mode inpaint --image jardim.jpg --mask mascara.png

## Search & Replace

python scripts/generate.py --prompt "a golden retriever" --mode search-replace --image parque.jpg --search "the cat"

## Erase An Object

python scripts/generate.py --mode erase --image foto.jpg --mask area.png

## List Models

python scripts/generate.py --list-models

## List Styles

python scripts/generate.py --list-styles

## Analyze Prompt (Automatic Suggestions)

python scripts/generate.py --prompt "anime warrior girl, widescreen" --analyze --json
```

## 3. Aspect Ratios

| Name | Ratio | Aliases | Typical use |
|------|-------|---------|-----------|
| square | 1:1 | ig, instagram, quadrado | Instagram feed |
| portrait | 2:3 | retrato, pinterest | Portrait, poster |
| landscape | 3:2 | paisagem, horizontal | Landscape, banner |
| photo | 4:5 | ig-feed | Optimized Instagram feed |
| wide | 16:9 | widescreen, youtube, cinema, wallpaper | Cinema, YT |
| ultrawide | 21:9 | — | Ultrawide monitor |
| stories | 9:16 | vertical, tiktok, ig-stories | Stories, Reels |
| phone | 9:21 | — | Phone wallpaper |

## 4. Styles (15 Presets)

Each style adds qualifiers to the prompt automatically:

| Style | Description | Ideal for |
|--------|-----------|-----------|
| photorealistic | Cinematic photorealism | Portraits, scenes |
| anime | Japanese anime/manga | Characters, scenes |
| digital-art | Detailed digital art | General illustrations |
| oil-painting | Classic oil painting | Classic art |
| watercolor | Fluid watercolor | Delicate art |
| pixel-art | Retro 8/16-bit pixel art | Retro games |
| 3d-render | Photorealistic 3D render | Products, 3D scenes |
| concept-art | Professional concept art | Games, films |
| comic | Stylized comics | Comic books |
| minimalist | Clean minimalist | Design, logos |
| fantasy | Epic fantasy art | RPG, medieval |
| sci-fi | Futuristic sci-fi | Cyberpunk, space |
| sketch | Pencil/charcoal drawing | Studies, drafts |
| pop-art | Vibrant pop art | Modern art |
| noir | Dramatic film noir | Dark atmosphere |

## 5. Output

Images saved to `data/outputs/` with the naming: `{mode}_{style}_{timestamp}_{index}.png`

Metadata saved in `.meta.json` with: original prompt, final prompt, model, aspect ratio, seed, time, size.

## Integration With Other Skills

- **ai-studio-image**: Complementary — Stability AI for art, Gemini for humanized photos
- **instagram**: Generate art → publish to Instagram
- **telegram**: Generate an image → send it via bot

## Rate Limits & Security

- **Community License**: 150 requests/10 seconds
- **Daily limit**: 100 images/day (configurable via `SAFETY_MAX_IMAGES_PER_DAY`)
- **Automatic retry** with exponential backoff on a 429
- **API key fallback** (primary + backups)

## File Reference

| File | When to consult |
|---------|-----------------|
| `references/setup-guide.md` | Initial setup, API key, troubleshooting |
| `references/prompt-engineering.md` | Advanced prompt techniques |
| `references/api-reference.md` | Endpoints, parameters, responses, errors |

## Best Practices

- Provide clear, specific context about your project and requirements
- Review all suggestions before applying them to production code
- Combine with other complementary skills for comprehensive analysis

## Common Pitfalls

- Using this skill for tasks outside its domain expertise
- Applying recommendations without understanding your specific context
- Not providing enough project context for accurate analysis

## Related Skills

- `ai-studio-image` - Complementary skill for enhanced analysis
- `comfyui-gateway` - Complementary skill for enhanced analysis
- `image-studio` - Complementary skill for enhanced analysis