Name: SDXL API: Stable Diffusion XL Text to Image
Brand: magicapi
SKU: api-magicapi-text-to-image-generator-stability-ai-sdxl
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎨 Text-to-Image Generator API (Stability AI SDXL)

## Overview
SDXL (Stable Diffusion XL) is a text-to-image model from Stability AI. Its developer describes it as a text-to-image generative AI model that creates beautiful images.

Send a `prompt` to generate 1 to 4 images. Add an `image` for image-to-image, or an `image` and a `mask` to inpaint part of a picture. An optional refiner stage (`refine`) adds a second pass.

## Features
- **Text to image**: generate 1 to 4 images (`num_outputs`) at the `width` and `height` you set (default 1024 x 1024).
- **Image to image**: pass an `image`; `prompt_strength` (0 to 1, default 0.8) sets how much of it is replaced.
- **Inpainting**: pass an `image` and a `mask`; white areas are repainted, black areas are kept.
- **Refiner**: `refine` is `no_refiner` (default), `expert_ensemble_refiner` (with `high_noise_frac`) or `base_image_refiner` (with `refine_steps`).
- **Sampling control**: 7 schedulers, `num_inference_steps` (1 to 500, default 50), `guidance_scale` (1 to 50, default 7.5), `negative_prompt` and `seed`.
- **Watermark**: `apply_watermark` is `true` by default; set it to `false` to turn it off.

## Use Cases
1. **Concept art and illustration**: explore styles and scenes from a text prompt.
2. **Marketing and social images**: generate visuals at the exact width and height of each placement.
3. **Photo variations**: restyle an existing image with image-to-image.
4. **Inpainting**: replace or repair a masked area of an image.

## Visual Examples
### Example Input
Prompt: "An astronaut riding a rainbow unicorn, cinematic, dramatic"

Settings: `width` 768, `height` 768, `refine` `expert_ensemble_refiner`, `high_noise_frac` 0.8, `scheduler` `K_EULER`, `num_inference_steps` 25, `guidance_scale` 7.5, `num_outputs` 1, `apply_watermark` `false`, `lora_scale` 0.6, `prompt_strength` 0.8, empty `negative_prompt`.

### Example Output
![SDXL output: an astronaut riding a rainbow unicorn in a cinematic scene](https://blog.api.market/wp-content/uploads/2026/10/sdxl-output-ta5kd12b-api-market.png)

## Input Parameters
| Field | Type | Required | Default | Allowed values | Description |
| --- | --- | --- | --- | --- | --- |
| `prompt` | string | No | `An astronaut riding a rainbow unicorn` |  | Input prompt |
| `negative_prompt` | string | No | `""` |  | Input negative prompt |
| `image` | string (URL) | No | none |  | Input image URL for img2img or inpaint mode |
| `mask` | string (URL) | No | none |  | Input mask URL for inpaint mode. Black areas will be preserved, white areas will be inpainted. |
| `width` | integer | No | `1024` |  | Width of output image |
| `height` | integer | No | `1024` |  | Height of output image |
| `num_outputs` | integer | No | `1` | `1` to `4` | Number of images to output. |
| `scheduler` | string | No | `K_EULER` | `DDIM`, `DPMSolverMultistep`, `HeunDiscrete`, `KarrasDPM`, `K_EULER_ANCESTRAL`, `K_EULER`, `PNDM` | Scheduler |
| `num_inference_steps` | integer | No | `50` | `1` to `500` | Number of denoising steps |
| `guidance_scale` | number | No | `7.5` | `1` to `50` | Scale for classifier-free guidance |
| `prompt_strength` | number | No | `0.8` | `0` to `1` | Prompt strength when using img2img or inpaint. 1.0 corresponds to full destruction of information in the image |
| `seed` | integer | No | none |  | Random seed. Leave blank to randomize the seed |
| `refine` | string | No | `no_refiner` | `no_refiner`, `expert_ensemble_refiner`, `base_image_refiner` | Which refine style to use |
| `high_noise_frac` | number | No | `0.8` | `0` to `1` | For expert_ensemble_refiner, the fraction of noise to use |
| `refine_steps` | integer | No | none |  | For base_image_refiner, the number of steps to refine; defaults to num_inference_steps |
| `apply_watermark` | boolean | No | `true` |  | Applies a watermark to enable determining if an image is generated in downstream applications. If you have other provisions for generating or deploying images safely, you can use this to disable watermarking. |
| `lora_scale` | number | No | `0.6` | `0` to `1` | LoRA additive scale. Only applicable on trained (LoRA) models; it has no effect on the base model. |
| `disable_safety_checker` | boolean | No | `false` |  | Disable the safety checker for generated images. |

## Pricing
- **Pay As You Go (PAYG) pricing**: you only pay for what you use.
- **Price**: $0.0058 per API unit.
- **1 API unit = 1 request with up to 5 seconds of processing time.** A request that runs longer uses one unit per started 5-second block; for example, 7 seconds of processing is 2 units ($0.0116).
- More images (`num_outputs`), larger sizes, more `num_inference_steps` and the refiner all add processing time, so they can use more units.
- **Example cost**: the example request (768 x 768, 25 steps, 1 image) took about 2.1 seconds of processing, which is 1 API unit: **$0.0058**.
- **Failed or cancelled predictions are not billed.**
- **GET requests to check prediction status** are free and don't count toward API unit usage.
- **No monthly subscription fee.**

## API Documentation

### Base URL
All API requests go to: `https://prod.api.market/api/v1/magicapi/text-to-image-generator-stability-ai-sdxl`

### Authentication
Send your api.market API key in the `x-api-market-key` header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT**: This API is asynchronous. The flow is:
1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Keep polling while `status` is `starting` or `processing`.
4. Stop when `status` is `succeeded` (read `output`), `failed` or `canceled` (read `error`).

A polling interval of 1 second and an overall timeout of 600 seconds (10 minutes) work well. The example request finished in about 8 seconds.

### Endpoints

#### Create a Prediction
```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/text-to-image-generator-stability-ai-sdxl/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "7762fd07cf82c948538e41f63f77d685e02b063e37e496e96eefd46c929f9bdc",
    "input": {
      "width": 768,
      "height": 768,
      "prompt": "An astronaut riding a rainbow unicorn, cinematic, dramatic",
      "refine": "expert_ensemble_refiner",
      "scheduler": "K_EULER",
      "lora_scale": 0.6,
      "num_outputs": 1,
      "guidance_scale": 7.5,
      "apply_watermark": false,
      "high_noise_frac": 0.8,
      "negative_prompt": "",
      "prompt_strength": 0.8,
      "num_inference_steps": 25
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ta5kd12bdxrmt0d1c6nvx6mr5m",
  "version": "7762fd07cf82c948538e41f63f77d685e02b063e37e496e96eefd46c929f9bdc",
  "status": "starting",
  "created_at": "2026-10-22T03:32:58.551Z"
}
```

#### Check Prediction Status
```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/text-to-image-generator-stability-ai-sdxl/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when the prediction has finished (200 OK):
```json
{
  "id": "ta5kd12bdxrmt0d1c6nvx6mr5m",
  "status": "succeeded",
  "output": [
    "https://blog.api.market/wp-content/uploads/2026/10/sdxl-output-ta5kd12b-api-market.png"
  ],
  "error": null,
  "created_at": "2026-10-22T03:32:58.551Z",
  "started_at": "2026-10-22T03:33:04.326Z",
  "completed_at": "2026-10-22T03:33:06.401Z"
}
```

`output` is a list of image URLs, one per image requested with `num_outputs`.

### Status Codes
- **201 Created**: prediction created (POST `/predictions`). This is the normal success response.
- **200 OK**: prediction details returned (GET `/predictions/{id}`).
- **400 Bad Request**: invalid input, for example a `num_outputs` above 4 or a `scheduler` that is not in the list.
- **401 Unauthorized**: missing or invalid API key.
- **404 Not Found**: no prediction with that ID.
- **429 Too Many Requests**: rate limit exceeded.
- **500 Internal Server Error** or **503 Service Unavailable**: temporary server problem; retry later.

## Rate Limits
All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.
## Error Handling
- Check the HTTP status code of every request and read the response body for the error message.
- A prediction can also end with `status` set to `failed`; the `error` field then explains why. Failed predictions are not billed.
- Retry 429, 500 and 503 responses with exponential backoff. Fix the input before retrying a 400.

## Implementation Guide
### Example Code

#### JavaScript
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/text-to-image-generator-stability-ai-sdxl";

async function createAndWaitForPrediction(input) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({ version: "7762fd07cf82c948538e41f63f77d685e02b063e37e496e96eefd46c929f9bdc", input })
  });

  if (response.status !== 201) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return pollForResults(prediction.id);
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function pollForResults(predictionId) {
  const maxTimeout = 600000;
  const pollInterval = 1000;
  const startTime = Date.now();

  while (Date.now() - startTime < maxTimeout) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(pollInterval);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
    "width": 768,
    "height": 768,
    "prompt": "An astronaut riding a rainbow unicorn, cinematic, dramatic",
    "refine": "expert_ensemble_refiner",
    "scheduler": "K_EULER",
    "lora_scale": 0.6,
    "num_outputs": 1,
    "guidance_scale": 7.5,
    "apply_watermark": false,
    "high_noise_frac": 0.8,
    "negative_prompt": "",
    "prompt_strength": 0.8,
    "num_inference_steps": 25
  }).then((output) => console.log(output));
```

#### Python
```python
import time
import requests

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/text-to-image-generator-stability-ai-sdxl"


def create_and_wait_for_prediction(input_data):
    headers = {"Content-Type": "application/json", "x-api-market-key": API_KEY}
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "7762fd07cf82c948538e41f63f77d685e02b063e37e496e96eefd46c929f9bdc", "input": input_data},
    )

    if response.status_code != 201:
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])


def poll_for_results(prediction_id):
    max_timeout = 600
    poll_interval = 1
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < max_timeout:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)

        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()

        if prediction["status"] == "succeeded":
            return prediction["output"]

        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(poll_interval)

    raise Exception("Prediction timed out after 10 minutes")


print(create_and_wait_for_prediction({
    "width": 768,
    "height": 768,
    "prompt": "An astronaut riding a rainbow unicorn, cinematic, dramatic",
    "refine": "expert_ensemble_refiner",
    "scheduler": "K_EULER",
    "lora_scale": 0.6,
    "num_outputs": 1,
    "guidance_scale": 7.5,
    "apply_watermark": False,
    "high_noise_frac": 0.8,
    "negative_prompt": "",
    "prompt_strength": 0.8,
    "num_inference_steps": 25
}))
```

## FAQ
- **How many images does one request return?**
  - `num_outputs`, from 1 to 4 (default 1). The request is billed on processing time, not on the number of images.
- **How do I inpaint?**
  - Send the source `image` and a `mask`. White areas of the mask are repainted from the prompt; black areas are kept.
- **What does the refiner do?**
  - `expert_ensemble_refiner` hands the last part of the denoising (set by `high_noise_frac`) to a refiner model; `base_image_refiner` refines the finished image for `refine_steps` steps.
- **How is a request billed?**
  - One API unit ($0.0058) covers up to 5 seconds of processing. Longer runs use one more unit per started 5-second block. The example used 1 unit.

- **Is the 201 response from POST an error?**
  - No. 201 Created means the prediction was accepted. Use the returned `id` to poll GET `/predictions/{id}` until `status` is `succeeded`, `failed` or `canceled`.
- **What if my prediction fails?**
  - Failed predictions are not billed. Read the `error` field, adjust the input and try again.

## 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.


SDXL API by Stability AI: generate up to 4 images per request from a text prompt with Stable Diffusion XL, plus image to image and inpainting.