# SnapEdit - AI Image Processing API

SnapAPI provides a comprehensive suite of AI-powered image processing endpoints including object removal, image enhancement, background removal, virtual try-on, image editing, and more.

## Authentication
Two methods supported (pick one):

**Option A — `api-key` header (simple):**
```
api-key: sk-snap-xxxxx
```

**Option B — Bearer token (OpenAI-compatible):**
```
Authorization: Bearer sk-snap-xxxxx
```

### API Key Format
All keys use the prefix `sk-snap-` for easy identification and leak detection.

### Security Best Practices
- **Never hardcode keys** in source code. Use environment variables (`SNAPAPI_KEY`).
- **Rotate keys** every 90 days. Create a new key before revoking the old one.
- **Use separate keys** for development and production.
- **Set quota limits** per key to prevent unexpected charges.
- **Revoke immediately** if a key is exposed. Go to [Dashboard → API Keys](https://snapapi.ai/en/dashboard/api-keys).

## Credits
Each API call costs credits based on the model used. See individual endpoint descriptions for credit costs. 1 credit = $0.0005.

## Image Input
Most endpoints accept image files or image URLs through fields such as `input_image`, `model_image`, and `cloth_image`. Mask inputs use `input_mask`.

## Rate Limits
All endpoints are rate-limited to **60 requests/minute** per API key. Rate limit info is returned in response headers:
- `x-ratelimit-limit-requests`: Max requests per window
- `x-ratelimit-remaining-requests`: Remaining requests
- `x-ratelimit-reset-requests`: Window reset time (ISO 8601)
- `retry-after`: Seconds to wait (only on 429)

## OpenAI SDK Compatibility
SnapAPI is compatible with the OpenAI Python/Node SDK. Just change the base URL:
```python
from openai import OpenAI
client = OpenAI(api_key='sk-snap-xxx', base_url='https://api.snapapi.ai/v1')
result = client.images.generate(model='snapapi/z-image', prompt='a cat')
print(result.data[0].url)
```

See the **OpenAI SDK** tag below for full endpoint documentation with all supported models.

### Response format (all image endpoints)
```json
{ 'created': 1745827200, 'data': [{ 'url': 'https://outputs.snapapi.ai/...' }] }
```

### Error format
```json
{ 'error': { 'message': '...', 'type': 'authentication_error', 'code': 401 } }
```

**Base URL:** `https://api.snapapi.ai`

**Authentication:** Include the `api-key: YOUR_API_KEY` header with every request.

**API version:** 1.0.0

## Image Input

Most endpoints accept image files or image URLs through fields such as `input_image`, `model_image`, and `cloth_image`. Mask inputs use `input_mask`.

---

# Detection

Detect objects, text, and wires in images for use with removal endpoints.

Models: `object-detection`, `remove-text`, `remove-wireline`

## Detect objects in image

**POST** `https://api.snapapi.ai/v1/images/detect-objects`

Automatically detect removable objects in an image. Use the returned `session_id` and selected `detected_objects` item with the [Remove Objects API](#removeObjects).

**Model:** `object-detection` — **Credit cost:** 1

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to detect objects in. |
| `lang` | string | No | Language for object class names.. Default: en |

### Responses

- **200**: Objects detected successfully (DetectionResponse)
```json
{
  "session_id": "sess_abc123",
  "detected_objects": [
    {
      "box": [
        120,
        50,
        300,
        400
      ],
      "mask": "base64_encoded_data...",
      "accuracy": 0.95,
      "object_type": "person",
      "object_description": "person"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Detect text in image

**POST** `https://api.snapapi.ai/v1/images/detect-text`

Detect text regions and return a mask. The returned `mask` can be used as `input_mask` in the [Remove Text API](#removeText), with optional manual modifications.

**Model:** `remove-text` — **Credit cost:** 1

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to detect text in. |

### Responses

- **200**: Text mask generated successfully (SimpleDetectionResponse)
```json
{
  "detected": true,
  "mask": "base64_encoded_data..."
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Detect wires/lines in image

**POST** `https://api.snapapi.ai/v1/images/detect-wires`

Detect wire, cable, and line regions and return a mask. The returned `mask` can be used as `input_mask` in the [Remove Wires API](#removeWires), with optional manual modifications.

**Model:** `remove-wireline` — **Credit cost:** 1

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to detect wires in. |

### Responses

- **200**: Wire mask generated successfully (SimpleDetectionResponse)
```json
{
  "detected": true,
  "mask": "base64_encoded_data..."
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


---

# Removal & Erase

Remove objects, text, wires, logos, and backgrounds from images.

Models: `remove-object-gan`, `remove-object-sd`, `remove-object-qwen`, `remove-text`, `remove-logo`, `remove-wireline`, `remove-background`

## Erase objects from image

**POST** `https://api.snapapi.ai/v1/images/remove-objects`

Remove objects from an image using a manual mask, selected detected objects, or both. To erase detected objects, first call the [Detect Objects API](#detectObjects), then provide `original_session_id` plus `mask_objects`.

Provide at least one erase target: `input_mask`, or `original_session_id` + `mask_objects`.

**Model:** `remove-object-gan`, `remove-object-sd`, `remove-object-qwen` — **Credit cost:** 3 (normal), 4 (super), 13 (ultra)

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to erase objects from. |
| `original_session_id` | string | No | Session ID returned by the Detect Objects API. Needed when using `mask_objects`. |
| `input_mask` | file | No | Manual brush mask image file or URL. Can be combined with `mask_objects`. |
| `mask_objects` | string | No | Selected object item or JSON array from `detected_objects`. Provide with `original_session_id`. |
| `erase_mode` | string | No | Erase mode.. Enum: normal, super, ultra. Default: normal |

### Responses

- **200**: Objects erased successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Erase text from image

**POST** `https://api.snapapi.ai/v1/images/remove-text`

Remove text from an image using a text mask. `input_mask` can come from the [Detect Text API](#detectText) and may be manually modified before removal.

**Model:** `remove-text` — **Credit cost:** 4

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to erase text from. |
| `input_mask` | file | Yes | Text mask image file or URL. Can be generated by the Detect Text API and modified manually. |
| `erase_mode` | string | No | Erase mode.. Enum: normal, super, ultra. Default: normal |

### Responses

- **200**: Text erased successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Erase logo from image

**POST** `https://api.snapapi.ai/v1/images/remove-logo`

Remove logos from an image. This API supports **automatic detection and removal**, or **manual removal within a selected region**.

**Model:** `remove-logo` — **Credit cost:** 5

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | The image file (or URL) to remove logo from. |
| `input_mask` | file | No | RGBG mask image (or URL) for manual logo selection. **If not provided**, the API will automatically detect and remove the logo. |
| `predict_mode` | string | No | Predict mode for the logo removal. `3.0` is better for general cases while `2.0` is suitable for emoji cases.. Enum: 2.0, 3.0. Default: 2.0 |

### Responses

- **200**: Logo erased successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Erase wires/lines from image

**POST** `https://api.snapapi.ai/v1/images/remove-wires`

Remove wires, cables, and line objects from an image using a mask. `input_mask` can come from the [Detect Wires API](#detectWires) and may be manually modified before removal.

**Model:** `remove-wireline` — **Credit cost:** 4

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to erase wires from. |
| `input_mask` | file | Yes | Wire mask image file or URL. Can be generated by the Detect Wires API and modified manually. |

### Responses

- **200**: Wires erased successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Remove background from image

**POST** `https://api.snapapi.ai/v1/images/remove-background`

Remove the background from an image. Returns a mask of the foreground object.

**Model:** `remove-background` — **Credit cost:** 1

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to remove the background from. |

### Responses

- **200**: Background removed successfully (RemoveBackgroundResponse)
```json
{
  "output_image_url": "https://outputs.snapapi.ai/outputs/abc123.png",
  "box": [
    10,
    20,
    300,
    400
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


---

# Enhance & Restore

Upscale, enhance, restore, and colorize images.

Models: `enhance-upscale-image`, `enhance-art-image`, `restore-image`, `colorize-image`

## Enhance and upscale image

**POST** `https://api.snapapi.ai/v1/images/enhance`

Upscale and enhance image resolution using AI. Supports input images with maximum width and height <= 1500 px.

**Model:** `enhance-upscale-image` — **Credit cost:** 6 (2x), 11 (4x)

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to enhance. Maximum width and height must be <= 1500 px. |
| `zoom_factor` | string | Yes | Upscale factor. `2` for 2x, `4` for 4x resolution.. Enum: 2, 4 |
| `enhance_faces` | string | No | Enable face enhancement.. Default: true |

### Responses

- **200**: Image enhanced successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Enhance art/cartoon image

**POST** `https://api.snapapi.ai/v1/images/enhance-art`

Upscale and enhance art, anime, or cartoon images. Supports input images with maximum width and height <= 1500 px.

**Model:** `enhance-art-image` — **Credit cost:** 2 (2x), 4 (4x)

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to enhance. Maximum width and height must be <= 1500 px. |
| `zoom_factor` | string | Yes | Upscale factor. `2` for 2x, `4` for 4x resolution.. Enum: 2, 4 |

### Responses

- **200**: Image enhanced successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Restore old images (Normal)

**POST** `https://api.snapapi.ai/v1/images/restore`

Restore and enhance old images, remove the scratches.

**Model:** `restore-image` — **Credit cost:** 1

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to restore. |

### Responses

- **200**: Image restored successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Restore old images (Pro)

**POST** `https://api.snapapi.ai/v1/images/restore/pro`

Restore old or degraded images using Qwen-Image-Edit. This endpoint uses restore mode internally, so users do not need to provide a mode.

**Model:** `restore-of-qwen-image-edit` — **Credit cost:** 13

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to restore. |

### Responses

- **200**: Image restored successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Colorize old images (Normal)

**POST** `https://api.snapapi.ai/v1/images/colorize`

Colorize old images.

**Model:** `colorize-image` — **Credit cost:** 1

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to colorize. |

### Responses

- **200**: Image colorized successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Colorize old images (Pro)

**POST** `https://api.snapapi.ai/v1/images/colorize/pro`

Add color to black-and-white images using Qwen-Image-Edit. This endpoint uses colorize mode internally, so users do not need to provide a mode.

**Model:** `colorize-of-qwen-image-edit` — **Credit cost:** 13

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to colorize. |

### Responses

- **200**: Image colorized successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Light restoration

**POST** `https://api.snapapi.ai/v1/images/light-restore`

Fix lighting issues such as underexposure, overexposure, and backlighting using Qwen-Image-Edit. This endpoint uses light restoration mode internally, so users do not need to provide a mode.

**Model:** `light-restoration-of-qwen-image-edit` — **Credit cost:** 21

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to restore lighting for. |

### Responses

- **200**: Image lighting restored successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


---

# Generation

Generate images from text prompts or transform photos into AI art.

Models: `generate-of-z-image`, `generate-of-qwen-image`, `fairy-ai-art-gen`

## Generate image with Z-Image

**POST** `https://api.snapapi.ai/v1/images/generates/zimage`

Text-to-image generation using Z-Image.

**Model:** `z-image-turbo` — **Credit cost:** 9

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `prompt` | string | Yes | Text prompt describing the image to generate. |
| `aspect_ratio` | string | No | Output aspect ratio.. Enum: 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16. Default: 1:1 |

### Responses

- **200**: Image generated successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Generate image with Qwen-Image

**POST** `https://api.snapapi.ai/v1/images/generates/qwen`

Text-to-image generation using Qwen-Image.

**Model:** `generate-of-qwen-image` — **Credit cost:** 9

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `prompt` | string | Yes | Text prompt describing the image to generate. |
| `aspect_ratio` | string | No | Output aspect ratio.. Enum: 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16. Default: 1:1 |

### Responses

- **200**: Image generated successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Generate AI art from image

**POST** `https://api.snapapi.ai/v1/images/generates/art`

Transform a photo into AI-generated art using various styles. The style list and preview images are in this [link](https://storage.googleapis.com/assets.snapedit.app/fairyai/anime_styles_6mar25.json).

The styles can be divided into two categories: `v1` (global image transformation) and `v2` (avatar-oriented transformation). `v1` is preferred for images with multiple subjects, while `v2` is designed for a single person.

**Model:** `fairy-ai-art-gen` — **Credit cost:** 6

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to transform into art. |
| `style` | string | Yes | Art style to apply. |

### Responses

- **200**: Art image generated successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Generate professional headshot from image

**POST** `https://api.snapapi.ai/v1/images/generates/headshot`

Generate a professional headshot from a person image using Qwen-Image-Edit. An example for the prompt is "Professional headshot image of the reference subject in a studio".

**Model:** `headshot-generation-of-qwen-image-edit` — **Credit cost:** 21

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Person image file or URL to transform into a headshot. |
| `prompt` | string | Yes | Prompt for outfit, background, lighting, or style preferences. |

### Responses

- **200**: Image generated successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Generate cartoon or sticker from image

**POST** `https://api.snapapi.ai/v1/images/generates/sticker`

Generate a cartoon or sticker-style image from an input image using Qwen-Image-Edit. An example for the prompt is "Turn the characters in the image into Apple iOS-style 3D avatars".

**Model:** `cartoon-sticker-generation-of-qwen-image-edit` — **Credit cost:** 21

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to transform into a cartoon or sticker. |
| `prompt` | string | Yes | Prompt describing the desired cartoon or sticker style. |

### Responses

- **200**: Image generated successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


---

# Editing

Edit images using AI prompts with various models and modes.

Models: `general-edit-of-qwen-image-edit`, `headshot-generation-of-qwen-image-edit`, `cartoon-sticker-generation-of-qwen-image-edit`, `light-restoration-of-qwen-image-edit`, `restore-of-qwen-image-edit`, `colorize-of-qwen-image-edit`, `inpaint-of-qwen-image-edit`, `general-edit-multi-of-qwen-image-edit`, `general-image-editing-of-flux-kontext`

## Edit image with AI prompt

**POST** `https://api.snapapi.ai/v1/images/edits`

Edit an image using natural language prompts powered by the Qwen-Image-Edit model. Use `editing` for general image edits and `inpaint` when editing a selected masked region.

**Model:** `general-edit-of-qwen-image-edit`, `inpaint-of-qwen-image-edit` — **Credit cost:** 13

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to edit. |
| `prompt` | string | Yes | Natural language editing instruction. |
| `mode` | string | Yes | Editing mode. Use `inpaint` with `input_mask`.. Enum: editing, inpaint |
| `input_mask` | file | No | Mask image file or URL for inpaint mode. |

### Responses

- **200**: Image edited successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Edit based on multiple input images with AI prompt

**POST** `https://api.snapapi.ai/v1/images/edits/multi`

Edit based on multiple images (up to 3) using natural language prompts powered by the Qwen-Image-Edit model. Supports multiple editing modes:<table><thead><tr><th>Mode</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>editing</td><td>General editing prompt</td><td>Put the man and the dog in a stadium</td></tr></tbody></table>

**Model:** `general-edit-multi-of-qwen-image-edit` — **Credit cost:** 26

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image_0` | file | Yes | First input image file or URL. |
| `input_image_1` | file | No | Second input image file or URL. |
| `input_image_2` | file | No | Third input image file or URL. |
| `prompt` | string | Yes | Natural language editing instruction. |
| `mode` | string | Yes | Editing mode.. Enum: editing |

### Responses

- **200**: Image edited successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


---

# Beauty & Style

AI-powered skin retouching, makeup transfer, and hairstyle transformation.

Models: `skin-natural-retouch`, `makeup-transfer`, `hairstyle-generation-lora-of-sd-1-5`

## Skin retouching

**POST** `https://api.snapapi.ai/v1/images/retouch-skin`

Apply natural skin retouching and enhancement to **all faces** in the image.

**Model:** `skin-natural-retouch` — **Credit cost:** 2

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to retouch. |

### Responses

- **200**: Skin beauty applied successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Makeup transfer

**POST** `https://api.snapapi.ai/v1/images/transfer-makeup`

Apply makeup styles to **all faces** in the image. The style list and preview images are in this [link](https://storage.googleapis.com/assets.snapedit.app/makeup/makeup_v1_1.json).

**Model:** `makeup-transfer` — **Credit cost:** 1

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to apply makeup to. |
| `style` | string | Yes | Makeup style to apply. |

### Responses

- **200**: Makeup applied successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Generate hairstyle transformation

**POST** `https://api.snapapi.ai/v1/images/hairstyle`

Transform the hairstyle in a face photo with multiple reference hairstyles in this [link](https://storage.googleapis.com/assets.snapedit.app/hairstyle/hair_styles_v3.json).

**Model:** `hairstyle-generation-lora-of-sd-1-5` — **Credit cost:** 6

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to transform. |
| `style` | string | Yes | Hairstyle to apply. |

### Responses

- **200**: Hairstyle generated successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


---

# Virtual Try-On

Virtual clothing try-on using AI.

Model: `virtual-tryon-clothes`

## Create virtual try-on task

**POST** `https://api.snapapi.ai/v1/images/try-on`

Create an asynchronous virtual try-on task. Upload a model (person) image and one or two clothing images to generate the try-on result.

This API supports either:<ol><li>One clothing item of type `upper`, `lower`, or `full`</li><li>Two clothing items simultaneously (`upper` and `lower`)</li></ol> 

Poll the GET endpoint with the returned `task_id` to retrieve results.

**Model:** `virtual-tryon-clothes` — **Credit cost:** 17

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `model_image` | file | Yes | Model/person image file or URL. |
| `cloth_image` | file | Yes | Clothing image file or URL. |
| `lower_cloth_image` | file | No | Lower clothing image file or URL. |
| `cloth_type` | string | Yes | Clothing type. |

### Responses

- **200**: Try-on task created successfully (TaskCreatedResponse)
```json
{
  "task_id": "task_abc123",
  "status": "CREATED",
  "created_at": 1745827200
}
```
- **400**: Missing required fields (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing `model_image`, `cloth_image`, or `cloth_type` fields"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


---

# Utility

Utility endpoints including outpaint, pose suggestion, and health check.

Models: `expand-image-outpaint`, `pose-suggestion-lora-of-qwen-image-edit-2509`

## Expand image (outpaint)

**POST** `https://api.snapapi.ai/v1/images/outpaint`

Expand an image beyond its original boundaries. Requires both the source image and a mask indicating the expansion area.

**Model:** `expand-image-outpaint` — **Credit cost:** 15

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Image file or URL to outpaint. |
| `input_mask` | file | Yes | Mask image file or URL defining the area to generate. |

### Responses

- **200**: Image outpainted successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Get pose suggestions

**POST** `https://api.snapapi.ai/v1/images/pose-suggest`

Generate AI pose suggestions for a reference scene image. The input image must have a maximum edge length of **512 pixels** to achieve the best output quality..

**Model:** `pose-suggestion-lora-of-qwen-image-edit-2509` — **Credit cost:** 28

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `input_image` | file | Yes | Reference scene image file or URL. |
| `num_models` | integer | Yes | Number of pose suggestions to generate. |
| `gender` | string | Yes | Gender for pose suggestions.. Enum: female, male |

### Responses

- **200**: Pose suggestions generated successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Health check

**GET** `https://api.snapapi.ai/v1/health`

Returns the health status of all SnapAPI services. No authentication required.

### Responses

- **200**: All services healthy
```json
{
  "status": "healthy",
  "checks": {
    "worker": "ok",
    "upstream": "ok",
    "backend": "ok",
    "kv": "ok"
  },
  "timestamp": "2026-04-28T10:00:00Z"
}
```


---

# Tasks

Poll and manage async tasks created by Virtual Try-On endpoints.

## Get task status

**GET** `https://api.snapapi.ai/v1/tasks/{task_id}`

Retrieve the status and result of an async task. Poll this endpoint after creating a task. Auto-fails tasks with `CREATED` status older than 120 seconds.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_id` | string | Yes | The task ID returned from the create task endpoint. |

### Responses

- **200**: Task status retrieved (TaskStatusResponse)
```json
{
  "task_id": "task_abc123",
  "status": "COMPLETED",
  "progress": 75,
  "output_image_url": "https://outputs.snapapi.ai/outputs/result.png",
  "error_msg": "string",
  "created_at": 0,
  "started_at": 0,
  "completed_at": 0
}
```
- **404**: Task not found (ErrorResponse)
```json
{
  "error": true,
  "message": "task abc123 doesn't exist"
}
```


## Cancel task

**DELETE** `https://api.snapapi.ai/v1/tasks/{task_id}`

Cancel a pending async task.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `task_id` | string | Yes | The task ID to cancel. |

### Responses

- **200**: Task cancelled
```json
{
  "message": "task abc123 cancelled"
}
```


---

# OpenAI SDK

Use SnapAPI with the OpenAI Python/Node SDK. Just change `base_url` and `api_key`:
```python
from openai import OpenAI
client = OpenAI(api_key='sk-snap-xxx', base_url='https://api.snapapi.ai/v1')
```

All models below work via `client.images.generate()` or `client.images.edit()`. The `model` parameter determines which AI model is used.

## Generate image from text (OpenAI SDK)

**POST** `https://api.snapapi.ai/v1/images/generations (OpenAI SDK)`

Generate images from text prompts using the OpenAI SDK `client.images.generate()` method.

## Setup
```python
from openai import OpenAI
client = OpenAI(api_key='sk-snap-xxx', base_url='https://api.snapapi.ai/v1')
```

## Supported Models

| Model | Description | Credit |
|-------|-------------|--------|
| `snapapi/z-image` | Text to Image (Z-Image) | 9 |
| `snapapi/qwen-image` | Text to Image (Qwen) | 9 |

## Examples

**Python:**
```python
result = client.images.generate(
    model='snapapi/z-image',
    prompt='a cute cat sitting on a cloud',
    size='1024x1024'
)
print(result.data[0].url)
```

**Node.js:**
```javascript
const result = await client.images.generate({
    model: 'snapapi/z-image',
    prompt: 'a cute cat sitting on a cloud',
    size: '1024x1024'
});
console.log(result.data[0].url);
```

## Size Mapping
`size` is auto-converted to `aspect_ratio`:
- `1024x1024` → `1:1`
- `1792x1024` → `16:9`
- `1024x1792` → `9:16`
- `1536x1024` → `3:2`
- `1024x1536` → `2:3`

### Responses

- **200**: Image generated successfully (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```


## Edit/process image (OpenAI SDK)

**POST** `https://api.snapapi.ai/v1/images/edits (OpenAI SDK)`

Process images using the OpenAI SDK `client.images.edit()` method. The `model` parameter determines which AI processing is applied.

## Setup
```python
from openai import OpenAI
client = OpenAI(api_key='sk-snap-xxx', base_url='https://api.snapapi.ai/v1')
```

## Supported Models

### Removal
| Model | Description | `prompt` | `mask` | Credit |
|-------|-------------|----------|--------|--------|
| `snapapi/remove-bg` | Remove background | not used | - | 1 |
| `snapapi/remove-logo` | Remove logo (auto-detect) | not used | optional | 5 |
| `snapapi/remove-object` | Remove object by mask | not used | **required** | 3-13 |
| `snapapi/remove-text` | Remove text by mask | not used | **required** | 4 |
| `snapapi/remove-wire` | Remove wires by mask | not used | **required** | 4 |

### Enhance & Restore
| Model | Description | `prompt` | Credit |
|-------|-------------|----------|--------|
| `snapapi/enhance-2x` | Upscale 2x | not used | 6 |
| `snapapi/enhance-4x` | Upscale 4x | not used | 11 |
| `snapapi/enhance-art-2x` | Upscale art/anime 2x | not used | 2 |
| `snapapi/enhance-art-4x` | Upscale art/anime 4x | not used | 4 |
| `snapapi/restore` | Restore old photo | not used | 1 |
| `snapapi/restore-pro` | Restore (Qwen AI) | not used | 13 |
| `snapapi/colorize` | Colorize B&W photo | not used | 1 |
| `snapapi/colorize-pro` | Colorize (Qwen AI) | not used | 13 |
| `snapapi/light-restore` | Fix lighting issues | not used | 21 |

### Generation from Image
| Model | Description | `prompt` | Credit |
|-------|-------------|----------|--------|
| `snapapi/headshot` | Professional headshot | outfit/style description | 21 |
| `snapapi/sticker` | Cartoon/sticker | style description | 21 |
| `snapapi/qwen-edit` | General AI edit | editing instruction | 13 |
| `snapapi/flux-kontext` | FLUX Kontext edit | editing instruction | 18 |

### Style-based (prompt = style_id)
| Model | Description | `prompt` | Credit |
|-------|-------------|----------|--------|
| `snapapi/hairstyle` | Transform hairstyle | style_id from [list](https://storage.googleapis.com/assets.snapedit.app/hairstyle/hair_styles_v3.json) | 6 |
| `snapapi/transfer-makeup` | Apply makeup style | style_id from [list](https://storage.googleapis.com/assets.snapedit.app/makeup/makeup_v1_1.json) | 1 |
| `snapapi/art` | Transform to AI art | style_id from [list](https://storage.googleapis.com/assets.snapedit.app/fairyai/anime_styles_6mar25.json) | 6 |

### Detection (returns JSON, not image)
| Model | Description | `prompt` | Credit |
|-------|-------------|----------|--------|
| `snapapi/detect-objects` | Detect removable objects | not used | 1 |
| `snapapi/detect-text` | Detect text regions | not used | 1 |
| `snapapi/detect-wires` | Detect wires/cables | not used | 1 |

### Utility
| Model | Description | `prompt` | `mask` | Credit |
|-------|-------------|----------|--------|--------|
| `snapapi/retouch-skin` | Skin retouching | not used | - | 2 |
| `snapapi/outpaint` | Expand image | not used | **required** | 15 |
| `snapapi/pose-suggest` | Pose suggestion | not used | - | 28 |
| `snapapi/qwen-edit-multi` | Multi-image edit | editing instruction | - | 26 |

## Examples

**Remove background:**
```python
result = client.images.edit(
    model='snapapi/remove-bg',
    image=open('photo.png', 'rb'),
    prompt=''
)
print(result.data[0].url)
```

**Enhance 4x:**
```python
result = client.images.edit(
    model='snapapi/enhance-4x',
    image=open('photo.png', 'rb'),
    prompt=''
)
```

**Headshot generation:**
```python
result = client.images.edit(
    model='snapapi/headshot',
    image=open('face.png', 'rb'),
    prompt='Professional studio headshot with soft lighting'
)
```

**Hairstyle (prompt = style_id):**
```python
result = client.images.edit(
    model='snapapi/hairstyle',
    image=open('face.png', 'rb'),
    prompt='ponytail'  # style_id from styles list
)
```

**Pose suggest (extra params via extra_body):**
```python
result = client.images.edit(
    model='snapapi/pose-suggest',
    image=open('scene.png', 'rb'),
    prompt='',
    extra_body={'num_models': 3, 'gender': 'female'}
)
```

**Multi-image edit (extra images via extra_body):**
```python
result = client.images.edit(
    model='snapapi/qwen-edit-multi',
    image=open('img1.png', 'rb'),
    prompt='Combine the two people in a park',
    extra_body={'input_image_1': 'https://example.com/img2.png'}
)
```

**Detect objects (returns JSON):**
```python
result = client.images.edit(
    model='snapapi/detect-objects',
    image=open('photo.png', 'rb'),
    prompt=''
)
print(result.model_dump())  # raw detection JSON
```

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `model` | string | Yes | Model to use. See supported models table above. |
| `image` | file | Yes | Input image file. |
| `prompt` | string | No | Depends on model: editing instruction, style_id, or empty string. See table above. |
| `mask` | file | No | Mask image. Required for: `remove-object`, `remove-text`, `remove-wire`, `outpaint`. |

### Responses

- **200**: Image processed successfully (or detection JSON for detect-* models) (SingleImageResponse)
```json
{
  "created": 1745827200,
  "data": [
    {
      "url": "https://outputs.snapapi.ai/outputs/abc123.png"
    }
  ]
}
```
- **400**: Missing required image input (ErrorResponse)
```json
{
  "error": true,
  "message": "Missing 'input_image' field"
}
```
- **429**: Rate limit exceeded or insufficient credits (ErrorResponse)
```json
{
  "error": true,
  "message": "Rate limit exceeded"
}
```
- **500**: Internal server error (ErrorResponse)
```json
{
  "error": true,
  "message": "Internal Server Error"
}
```