# Stability AI Integration via LowCodeAPI

## Overview

Stability AI is an AI image and video generation platform with advanced diffusion models for creating visual content. The Stability AI API provides:

- **Text to Image** - Generate images from text descriptions
- **Image to Image** - Modify images based on text prompts
- **Inpainting** - Edit and fill in parts of images
- **Upscaling** - Enhance and upscale image resolution
- **Engine Management** - List and manage available AI engines

## Base Endpoint

```
https://api.lowcodeapi.com/stabilityai/
```

## Authentication

LowCodeAPI handles authentication automatically using API Key header authentication. You only need to:

1. **Sign up** at [Stability AI](https://stability.ai) to get your API Key
2. **Connect your account** in the LowCodeAPI dashboard
3. **Use your `api_token`** in all requests

The `api_token` is your LowCodeAPI authentication token. LowCodeAPI will automatically:
- Fetch your Stability AI API key
- Apply it to each request via the Authorization header

**Auth Type**: API Key (Header)

## API Categories

- **Video Generation AI** - AI-powered visual content creation

## Common Endpoints

### Category: Engines

#### List Engines

**Method**: `GET` | **LowCodeAPI Path**: `/v1/engines/list`

**Full URL**:
```
https://api.lowcodeapi.com/stabilityai/v1/engines/list?api_token={api_token}
```

**Description**: List all AI engines available to your organization/user.

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/stabilityai/v1/engines/list?api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [List Engines](https://platform.stability.ai/docs/api-reference#tag/Engines)

---

### Category: Generation

#### Text to Image

**Method**: `POST` | **LowCodeAPI Path**: `/v1/generation/engine_id/text-to-image`

**Full URL**:
```
https://api.lowcodeapi.com/stabilityai/v1/generation/engine_id/text-to-image?engine_id={engine_id}&api_token={api_token}
```

**Description**: Generate images from text prompts using Stable Diffusion.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `engine_id` | string | Yes | ID of the engine to use (e.g., stable-diffusion-v1-6, stable-diffusion-xl-1024) |

**Request Body**:
```json
{
  "text_prompts": [
    {
      "text": "A beautiful landscape with mountains and a lake",
      "weight": 1
    }
  ],
  "cfg_scale": 7,
  "height": 1024,
  "width": 1024,
  "steps": 30,
  "samples": 1
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text_prompts` | array | Yes | Array of text prompts with weights |
| `cfg_scale` | number | No | How strictly to follow prompt (default: 7) |
| `height` | integer | No | Image height (default: 1024) |
| `width` | integer | No | Image width (default: 1024) |
| `steps` | integer | No | Number of inference steps (default: 30) |
| `samples` | integer | No | Number of images to generate (default: 1) |
| `seed` | integer | No | Random seed for reproducibility |

**Example Request**:
```bash
# Replace ENGINE_ID with actual engine ID
curl -X POST "https://api.lowcodeapi.com/stabilityai/v1/generation/engine_id/text-to-image?engine_id=stable-diffusion-xl-1024&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text_prompts": [
      {"text": "A beautiful landscape with mountains and a lake", "weight": 1}
    ],
    "cfg_scale": 7,
    "height": 1024,
    "width": 1024,
    "steps": 30,
    "samples": 1
  }'
```

**Official Documentation**: [Text to Image](https://platform.stability.ai/docs/api-reference)

---

#### Image to Image

**Method**: `POST` | **LowCodeAPI Path**: `/v1/generation/engine_id/image-to-image`

**Full URL**:
```
https://api.lowcodeapi.com/stabilityai/v1/generation/engine_id/image-to-image?engine_id={engine_id}&api_token={api_token}
```

**Description**: Modify an image based on a text prompt.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `engine_id` | string | Yes | ID of the engine to use |

**Request Body**:
```json
{
  "text_prompts": [
    {
      "text": "A sunset over the ocean",
      "weight": 1
    }
  ],
  "init_image": "data:image/png;base64,iVBORw0KGgo...",
  "init_image_mode": "IMAGE_STRENGTH",
  "image_strength": 0.35,
  "steps": 30,
  "seed": 0
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `text_prompts` | array | Yes | Array of text prompts |
| `init_image` | string | Yes | Base64-encoded input image |
| `init_image_mode` | string | No | IMAGE_STRENGTH or STEP_SCHEDULE_* |
| `image_strength` | number | No | How much to preserve init image (0-1) |
| `steps` | integer | No | Number of steps (default: depends on mode) |
| `seed` | integer | No | Random seed |

**Example Request**:
```bash
# Replace ENGINE_ID with actual engine ID
curl -X POST "https://api.lowcodeapi.com/stabilityai/v1/generation/engine_id/image-to-image?engine_id=stable-diffusion-xl-1024&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text_prompts": [{"text": "A sunset over the ocean", "weight": 1}],
    "init_image": "data:image/png;base64,iVBORw0KGgo...",
    "init_image_mode": "IMAGE_STRENGTH",
    "image_strength": 0.35
  }'
```

**Official Documentation**: [Image to Image](https://platform.stability.ai/docs/api-reference)

---

## Usage Examples

### Example 1: Generate Images from Text

Create images with text descriptions:

```bash
# Step 1: List available engines
# No ID needed - lists all engines
curl -X GET "https://api.lowcodeapi.com/stabilityai/v1/engines/list?api_token=YOUR_API_TOKEN"

# Step 2: Generate image from text
# No ID needed in path - engine_id in query, creates new generation
curl -X POST "https://api.lowcodeapi.com/stabilityai/v1/generation/engine_id/text-to-image?engine_id=stable-diffusion-xl-1024&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text_prompts": [{"text": "A futuristic cityscape at sunset", "weight": 1}],
    "cfg_scale": 7,
    "height": 1024,
    "width": 1024,
    "steps": 30,
    "samples": 1
  }'
```

### Example 2: Modify Existing Images

Transform images with AI:

```bash
# Modify an image with a text prompt
# No ID needed in path - engine_id in query
curl -X POST "https://api.lowcodeapi.com/stabilityai/v1/generation/engine_id/image-to-image?engine_id=stable-diffusion-xl-1024&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text_prompts": [{"text": "Add a beautiful blue sky", "weight": 1}],
    "init_image": "data:image/png;base64,iVBORw0KGgo...",
    "image_strength": 0.35,
    "steps": 30
  }'
```

### Example 3: Generate Multiple Images

Create batch of images:

```bash
# Generate multiple images with different seeds
# No ID needed in path - engine_id in query
curl -X POST "https://api.lowcodeapi.com/stabilityai/v1/generation/engine_id/text-to-image?engine_id=stable-diffusion-v1-6&api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text_prompts": [{"text": "A serene mountain landscape", "weight": 1}],
    "samples": 4,
    "steps": 25,
    "cfg_scale": 7
  }'
```

## Complete Endpoint Reference

For a complete list of all 7 endpoints and their parameters, refer to:

- **OpenAPI Definition**: https://backend.lowcodeapi.com/stabilityai/definition
- **Official Stability AI Documentation**: https://platform.stability.ai/docs/getting-started

## Rate Limits & Best Practices

- **Rate Limit**: Refer to your Stability AI plan for rate limits
- **Best Practices**:
  - Use appropriate engine for your use case (SDXL for quality, SD 1.6 for speed)
  - Adjust cfg_scale for prompt adherence (higher = stricter)
  - Use fewer steps for faster generation, more for quality
  - Set seed for reproducible results
  - Test with lower resolution first, then upscale
  - Use appropriate image strength for image-to-image tasks

## Error Handling

All responses are wrapped in a `data` key:
```json
{
  "data": {
    // Actual response from Stability AI
  }
}
```

Common errors:
- **400**: Invalid request parameters or image format
- **401**: Invalid API key
- **429**: Rate limit exceeded
- **500**: Generation failed or server error