> For the complete documentation index, see [llms.txt](https://docs.apismart.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.apismart.ai/api-guides/image-generation-api.md).

# Image Generation API

Use the Image Generation API to create images with supported ApiSmart image models.

Specify the exact **Model ID**, provide a prompt, and send any additional fields required by the selected model.

For the API Base URL, authentication, and general request rules, see [**API Basics**](/api-guides/api-basics.md).

***

### API Endpoint

```
POST https://gw.apismart.ai/v1/images/generations
```

Required headers:

```http
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

> ⚠️ **Important:** Image models may support different parameters and input types. Always follow the selected model’s **Code Example**.

***

### Send a Basic Request

The following example shows a basic text-to-image request:

```bash
curl https://gw.apismart.ai/v1/images/generations \
  -H "Authorization: Bearer $APISMART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_ID",
    "prompt": "A mountain village in the morning light"
  }'
```

Replace `YOUR_MODEL_ID` with the exact Model ID shown on the selected model’s details page.

***

### Understand the Request

A basic image request may include:

| Field    | Description                          |
| -------- | ------------------------------------ |
| `model`  | Exact Model ID to use                |
| `prompt` | Description of the image to generate |

Example:

```json
{
  "model": "YOUR_MODEL_ID",
  "prompt": "A mountain village in the morning light"
}
```

Depending on the model, additional fields may control:

* Image size or resolution
* Number of generated images
* Image quality
* Reference images
* Image-to-image generation
* Other model-specific settings

Do not assume that every image model accepts the same fields or values.

***

### Python Example

```python
import os
import requests

api_key = os.getenv("APISMART_API_KEY")

if not api_key:
    raise RuntimeError("APISMART_API_KEY is not set.")

response = requests.post(
    "https://gw.apismart.ai/v1/images/generations",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    json={
        "model": "YOUR_MODEL_ID",
        "prompt": "A mountain village in the morning light",
    },
    timeout=120,
)

response.raise_for_status()

result = response.json()
print(result)
```

The exact response fields depend on the selected image model. Review the model’s **Code Example** before extracting generated image data in your application.

***

### Image-to-Image and Reference Inputs

Some models may support image-to-image generation or reference-image workflows.

These models can require additional fields beyond `prompt`.

Before sending the request:

1. Confirm that the selected model supports the required capability.
2. Review its **Code Example**.
3. Use the exact field names and input format shown there.

***

### Understand Billing

Image models may use billing methods such as:

```
$0.04/image
```

Pricing can also depend on model-specific settings.

Review the model’s **Price Configuration** before sending high-volume requests.

For more details, see [**Understand Model Pricing and Billing**](/models-and-pricing/model-pricing-and-billing.md).

***

### 🛠️ Common Problems

| Problem                   | What to Check                                           |
| ------------------------- | ------------------------------------------------------- |
| **Authentication failed** | API Token status and Bearer header                      |
| **Model not found**       | Exact Model ID and capitalization                       |
| **Invalid request**       | Required fields and model-specific parameters           |
| **Unsupported input**     | Whether the model supports the requested image workflow |
| **Insufficient balance**  | Current Balance and API Token remaining allowance       |

When troubleshooting, review the related request in [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md) and save the **Request ID** when available.

> 🔐 Never provide your full API Token to support.

***

### 🚀 Next Steps

Continue with:

* [**Choose a Model and Find Its Model ID**](/models-and-pricing/models-and-model-ids.md)
* [**Understand Model Pricing and Billing**](/models-and-pricing/model-pricing-and-billing.md)
* [**Video Generation API**](/api-guides/video-generation-api.md)
* [**Usage Logs and Costs**](/api-usage/usage-logs-and-costs.md)