# Image Generation API

Generate images from text prompts with the image model of your choice, and get each image as a file link with its size, the exact model version, its maker, the options used and the exact cost of the call. You pay exactly what each image costs at the model's own rates.

**Pricing:** Metered: you pay exactly each call's cost at the selected model's rates (default Google: Nano Banana (Gemini 2.5 Flash Image): $0.30 per 1M input image tokens; $30.00 per 1M output image tokens). Each model's rates are listed with the `model` parameter's options in the API schema.

**Endpoint:** `POST /v1/data/ai/images/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompts` | array | Yes | What to draw, one prompt per line. Each prompt makes Count images, one call and one row each. |
| `model` | string | No | The image model. Pick from the list (popular models first). Each model shows its own rates, per image or per 1M image tokens, and that is exactly what each image costs. |
| `aspectRatio` | string | No | The image shape, e.g. 1:1 or 16:9. Leave blank for the model's default. Only the ratios the selected model offers are accepted. |
| `resolution` | string | No | The size tier, e.g. 1K, 2K or 4K, on models that offer one. Leave blank for the model's default. |
| `quality` | string | No | Rendering quality (low, medium, high...) on models that offer it. Leave blank for the model's default. |
| `outputFormat` | string | No | The file type (png, jpeg, webp...) on models that offer a choice. Leave blank for the model's default. |
| `count` | integer | No | How many images to make for each prompt, 1 to 4. Each image is its own call and its own row. |
| `referenceImages` | array | No | Optional public image URLs to edit or draw from, for models that take reference images. One prompt with several images runs the prompt on each image; several prompts with one image uses that image for each prompt. Several prompts with several images is refused. |

## Example

`?wait=true` holds the request open until the run finishes (up to 60s) and returns the rows inline: one request, no polling.

```bash
curl -X POST "https://api.mindcase.co/v1/data/ai/images/run?wait=true" \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{"prompts":["..."]}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/v1/data/ai/images/run",
    params={"wait": "true"},
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {
    "prompts": [
        "..."
    ]
}},
)
rows = resp.json()["data"]
```

## Longer runs

If the run is still going at the 60s ceiling you get back `{ job_id, status: "running" }` instead of rows (same if the result is over 100 rows; those come back `truncated`). Poll with that `job_id`:

```bash
# 1) check status
curl https://api.mindcase.co/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, SDKs, MCP): https://mindcase.co/skills.md

## Response columns

| Field | Display name | Type |
|-------|--------------|------|
| `id` | ID | text |
| `prompt` | Prompt | text |
| `referenceImage` | Reference Image | text |
| `fileUrl` | File URL | text |
| `mimeType` | MIME Type | text |
| `width` | Width | number |
| `height` | Height | number |
| `model` | Model | text |
| `provider` | Provider | text |
| `aspectRatio` | Aspect Ratio | text |
| `resolution` | Resolution | text |
| `quality` | Quality | text |
| `outputFormat` | Output Format | text |
| `costUsd` | Cost (USD) | number |
| `error` | Error | text |
| `createdAt` | Created At | datetime |
