Name: GPU Image API
Brand: quickpod
SKU: api-quickpod-aiquick-image
Availability: InStock
Author: API Market

Anil Singh

# GPU Image API

## Overview

The GPU Image API is a powerful text-to-image service that leverages a remote GPU image generation cluster to create stunning visuals from simple text prompts. This API is designed for developers who need to programmatically generate images for a wide range of applications, from dynamic content creation to product mockups and internal tool automation. It provides results either as a convenient base64 encoded string or a normalized image payload, making it easy to integrate into existing workflows without extra download steps.

## Features

- **Text-to-Image Generation:** Transform descriptive text prompts into high-quality images.
- **Flexible Output Formats:** Choose between a direct base64 image (for single image generation) or a normalized array of image assets (for multi-image generation), each including base64 data.
- **Configurable Image Properties:** Control parameters like the number of images (`n`), output size (`size`), generation lane (`lane` for speed or quality), and model selection.
- **Multiple Models:** Access various underlying image generation models to suit diverse aesthetic and stylistic needs.
- **Tiered Access:** Utilize different service tiers (demo, registered, paid) to match your usage requirements.
- **Direct Image Payload:** Returned base64 encoded images simplify storage, transmission, and post-processing.
- **Health Endpoints:** Monitor the status of the API service and its upstream image workers.

## Use Cases

1.  **Automated Content Creation for E-commerce:** Dynamically generate product images or lifestyle shots based on product descriptions, facilitating rapid catalog updates and marketing campaigns without the need for manual photography.
2.  **Visual Asset Generation for Game Development:** Create diverse textures, character portraits, or environmental elements for games by simply providing text prompts, accelerating asset pipeline and fostering creative iterations.
3.  **Personalized Marketing & Ad Campaigns:** Generate unique and personalized banner ads, social media graphics, or email visuals tailored to specific user segments or promotional themes, improving engagement and conversion rates.
4.  **Prototyping and Mockup Generation:** Quickly visualize design concepts for websites, applications, or physical products by converting design briefs into visual mockups, streamlining the ideation and feedback process.
5.  **Internal Tools & Dashboard Integration:** Build custom tools that turn data insights or user inputs into illustrative images for reports, presentations, or dashboards, enhancing data visualization and internal communication.

## Pricing

The GPU Image API operates on a usage-based pricing model:
- **1 API unit equals 1 image processed.**
- Different pricing tiers are available based on usage volume, offering cost efficiencies for higher-volume users.

## API Documentation

### Base URL

All API requests should be made to: `https://prod.api.market/api/v1/quickpod/aiquick-image`

### Authentication

Authentication is handled via an API key. Include your API key in the request header for every call:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Endpoints

#### GET /api/v1/quickpod/aiquick-image/health

Checks the health status of the API service.

**Summary:** Service health
**Tags:** Health

**Example Request:**
```bash
curl -X GET "https://prod.api.market/api/v1/quickpod/aiquick-image/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**
```json
{
  "ok": true,
  "service": "quickpod-image-service",
  "default_model": "black-forest-labs/FLUX.1-schnell",
  "max_inflight": 20
}
```

#### GET /api/v1/quickpod/aiquick-image/image/health

Checks the health status of the upstream image worker service.

**Summary:** Upstream image worker health
**Tags:** Health

**Example Request:**
```bash
curl -X GET "https://prod.api.market/api/v1/quickpod/aiquick-image/image/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**
```json
{
  "ok": true
}
```

#### GET /api/v1/quickpod/aiquick-image/image/models

Lists the configured image generation models available through the API.

**Summary:** List configured generation models
**Tags:** Image

**Example Request:**
```bash
curl -X GET "https://prod.api.market/api/v1/quickpod/aiquick-image/image/models" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Example Response (200 OK):**
```json
{
  "object": "list",
  "data": [
    {
      "id": "black-forest-labs/FLUX.1-schnell",
      "object": "model",
      "owned_by": "quickpod"
    },
    {
      "id": "gpt-image-1",
      "object": "model",
      "owned_by": "quickpod"
    }
  ]
}
```

#### POST /api/v1/quickpod/aiquick-image/image/generate

Generates one or more images from a text prompt. This simplified endpoint returns the first generated image as a base64 string directly (`image_base64`) and also includes a `data` array with normalized image items.

**Summary:** Generate one or more images and return base64
**Tags:** Image

**Request Body Schema (SimpleImageRequest):**
| Field              | Type      | Description                                                    | Default                             | Required |
| :----------------- | :-------- | :------------------------------------------------------------- | :---------------------------------- | :------- |
| `prompt`           | `string`  | The text prompt to generate images from.                       |                                     | Yes      |
| `size`             | `string`  | The desired image resolution (e.g., "1024x1024").              | "1024x1024"                         | No       |
| `n`                | `integer` | The number of images to generate (1 to 4).                     | 1                                   | No       |
| `model`            | `string`  | The specific model to use for generation.                      | "black-forest-labs/FLUX.1-schnell"  | No       |
| `tier`             | `string`  | The processing tier (`demo`, `registered`, `paid`).             | "demo"                              | No       |
| `lane`             | `string`  | The generation lane (`fast` or `quality`).                     | "fast"                              | No       |
| `private_by_default` | `boolean` | If true, images are not made public by default.                 | true                                | No       |

**Example Request:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-image/image/generate" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "model": "black-forest-labs/FLUX.1-schnell",
    "prompt": "A cinematic mountain landscape at sunrise, ultra-detailed",
    "size": "1024x1024",
    "n": 1,
    "tier": "demo",
    "lane": "fast"
  }'
```

**Example Response (200 OK):**
```json
{
  "model": "black-forest-labs/FLUX.1-schnell",
  "prompt": "A cinematic mountain landscape at sunrise, ultra-detailed",
  "size": "1024x1024",
  "n": 1,
  "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "mime_type": "image/png",
  "job_id": "img_f8701bd6f3c5492b",
  "status": "succeeded",
  "latency_seconds": 1.96
}
```

#### POST /api/v1/quickpod/aiquick-image/image/generations

Generates one or more images, returning them as a normalized `data` array where each image item includes its base64 representation. This endpoint is ideal when you need to handle multiple generated images consistently.

**Summary:** Generate one or more images with base64 normalization
**Tags:** Image

**Request Body Schema (ImageGenerationRequest):**
| Field              | Type      | Description                                                    | Default                             | Required |
| :----------------- | :-------- | :------------------------------------------------------------- | :---------------------------------- | :------- |
| `prompt`           | `string`  | The text prompt to generate images from.                       |                                     | Yes      |
| `size`             | `string`  | The desired image resolution (e.g., "1024x1024").              | "1024x1024"                         | No       |
| `n`                | `integer` | The number of images to generate (1 to 4).                     | 1                                   | No       |
| `model`            | `string`  | The specific model to use for generation.                      | "black-forest-labs/FLUX.1-schnell"  | No       |
| `tier`             | `string`  | The processing tier (`demo`, `registered`, `paid`).             | "demo"                              | No       |
| `lane`             | `string`  | The generation lane (`fast` or `quality`).                     | "fast"                              | No       |
| `private_by_default` | `boolean` | If true, images are not made public by default.                 | true                                | No       |

**Example Request:**
```bash
curl -X POST "https://prod.api.market/api/v1/quickpod/aiquick-image/image/generations" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "model": "black-forest-labs/FLUX.1-schnell",
    "prompt": "Anime style portrait of a cyberpunk engineer, neon rim light, rain reflections, highly detailed, 4k illustration",
    "size": "1024x1536",
    "n": 1,
    "tier": "demo",
    "lane": "fast"
  }'
```

**Example Response (200 OK):**
```json
{
  "job_id": "img_f8701bd6f3c5492b",
  "model": "black-forest-labs/FLUX.1-schnell",
  "status": "succeeded",
  "latency_seconds": 1.96,
  "data": [
    {
      "index": 0,
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "mime_type": "image/png",
      "source_url": "/assets/img_f8701bd6f3c5492b_0.png",
      "width": 768,
      "height": 768,
      "asset_id": "img_f8701bd6f3c5492b_0"
    }
  ]
}
```

## Status Codes

- **200 OK:** Request successful. The API processed the request and returned the expected data.
- **201 Created:** Resource successfully created. While not typical for image generation outputs, this indicates successful creation.
- **400 Bad Request:** Invalid input parameters or malformed request. Check your request body and query parameters against the API documentation. The response body will contain details about the error.
- **401 Unauthorized:** Missing or invalid API key. Ensure your `x-api-market-key` header is correctly set with a valid key.
- **403 Forbidden:** Valid API key but insufficient permissions. Your API key might not have the necessary access rights for the requested operation.
- **404 Not Found:** Resource not found. This could mean an incorrect endpoint URL.
- **422 Unprocessable Entity:** Request validation failed. Similar to 400, but specifically indicates that the request was well-formed but could not be processed due to semantic errors in the input data (e.g., an invalid `size` format).
- **429 Too Many Requests:** Rate limit exceeded. You have sent too many requests in a given time frame. Implement a retry-with-backoff strategy.
- **500 Internal Server Error:** Server-side error. An unexpected error occurred on the API server.
- **503 Service Unavailable:** Service temporarily unavailable. This could be due to maintenance, upstream issues, or high load. The API might also return this if the upstream image service is unavailable or times out. Implement retry logic.

## Rate Limits

Specific rate limits are applied to ensure fair usage and service stability. If you exceed the allocated rate limits, you will receive a `429 Too Many Requests` HTTP status code. To handle rate limits gracefully, implement exponential backoff and retry mechanisms in your client application. Repeatedly hitting rate limits without proper handling may lead to temporary blocking of your API key.

## Error Handling

Effective error handling is crucial for robust API integrations.
- **Interpret Error Responses:** Always inspect the HTTP status code and the response body for detailed error messages. Error responses are typically JSON objects providing insights into what went wrong.
- **Common Errors:**
  - **400/422 (Bad Request/Validation Error):** Indicates an issue with your request payload or parameters. Double-check your `prompt`, `size`, `n`, `model`, `tier`, and `lane` values against the schema definitions.
    - **401 (Unauthorized):** Verify your API key is correct and included in the `x-api-market-key` header.
    - **500/503 (Server Error/Service Unavailable):** These are usually transient server-side issues.
- **Recommended Retry Strategies:**
  - For `429 Too Many Requests` and `5xx` server errors, implement an exponential backoff strategy. This means waiting for an increasing amount of time between retries (e.g., 1 second, then 2 seconds, then 4 seconds, etc.) up to a maximum number of retries.
    - For `400` or `422` errors, retrying without modifying the request is unlikely to resolve the issue. These errors require fixing the input data.

**Example Error Response (400 Bad Request):**
```json
{
  "detail": "Invalid prompt provided."
}
```

**Example Error Response (422 Unprocessable Entity):**
```json
{
  "detail": [
    {
      "loc": [
        "body",
        "size"
      ],
      "msg": "value does not match regex \"^[0-9]{2,4}x[0-9]{2,4}$\"",
      "type": "value_error.str.regex"
    }
  ]
}
```

## FAQ

**What is the maximum number of images I can generate in a single request?**

You can generate up to 4 images per request using the `n` parameter.

**Can I specify which AI model to use?**

Yes, you can specify a `model` in your request body. You can list available models using the `/image/models` endpoint.

**How are images returned?**

Images are returned as base64 encoded strings within the API response. For `/image/generate`, the first image is directly available in `image_base64`, and for `/image/generations`, all generated images are in the `data` array with their `b64_json` fields.

**What image sizes are supported?**

The `size` parameter accepts dimensions in the format `WIDTHxHEIGHT`, such as `1024x1024`. Supported ranges are typically from 256x256 up to 1536x1536, but can vary by model.

**Is there a way to get direct URLs to the generated images instead of base64?**

The API primarily returns images as base64 strings to facilitate direct embedding and processing. The `source_url` field might be present for some internal tracking but is not intended for public access or direct download. To store images, you should decode the base64 string and save it.

**What happens if the API encounters an error during image generation?**

The API will return an appropriate HTTP status code (e.g., 400, 422, 500, 503) along with a JSON error body detailing the issue. Refer to the Error Handling section for guidance.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.

Generate images from text prompts on GPU, list the available models, and receive base64 output ready to store or return straight from your app.