# Midjourney — /images/generations

The Midjourney image model (Beta), V8.2 by default. Prompts and parameters are written as on midjourney.com; each job is a set of four PNG originals, billed once, and upscale, vary, remix, zoom and pan run on the same endpoint.

**Endpoint:** `POST https://kovapi.com/v1/images/generations`

## Quick start

An asynchronous job like the other image calls: submit, get a job id, poll for the result. The three steps below are text-to-image, the result, and upscaling picture 2.

**Step 1: submit text-to-image (parameters at the end of the prompt)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2", "speed": "fast"}'
```

Response (HTTP 202)

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1795248736,
  "model": "midjourney"
}
```

**Step 2 · Poll every 2–3 seconds until `status` is `succeeded` or `failed`**

```
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

data holds the four PNG originals (in order 1-4); actions lists what the job can do next.

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1795248736,
  "model": "midjourney",
  "data": [
    {"url": "https://img.kovapi.com/i/5b2c0e8a1f3d4c6b9a7e2d1c0b3a4f5e.png"},
    {"url": "https://img.kovapi.com/i/0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f.png"},
    {"url": "https://img.kovapi.com/i/7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d.png"},
    {"url": "https://img.kovapi.com/i/3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b.png"}
  ],
  "usage": {"images": 4, "model": "midjourney", "speed": "fast", "action": "imagine"},
  "actions": ["upscale", "vary", "remix", "reroll", "zoom", "pan"]
}
```

**Step 3: continue the job -- upscale picture 2 (same endpoint, with task_id, action and index)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "task_id": "img_7f3c9a1e2b4d6f8a0c1e3b5d", "action": "upscale", "index": 2, "mode": "subtle"}'
```

**Complete example (Python: submit, wait, save to disk)**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

def run(body):
    job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json=body).json()
    if "error" in job:
        raise SystemExit(job["error"]["message"])
    while job["status"] not in ("succeeded", "failed"):
        time.sleep(5)
        job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()
    if job["status"] == "failed":
        raise SystemExit(job["error"]["message"])
    return job

# text-to-image, then upscale picture 2
grid = run({"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2"})
print([d["url"] for d in grid["data"]], grid["actions"])
big = run({"model": "midjourney", "task_id": grid["id"], "action": "upscale", "index": 2})
with open("midjourney-2.png", "wb") as f:
    f.write(requests.get(big["data"][0]["url"]).content)
```

## Authentication
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| model | string | Yes | Model ID, here midjourney. |
| prompt | string | No | The prompt, with Midjourney's parameters at the end as on midjourney.com (--ar, --v, --niji, --s, --c, --w, --seed, --no, --sref, --oref, --cref, --iw, --raw, --tile, --hd, --draft). Required for text-to-image, remix and edit; up to 6000 characters. --repeat and {a, b} are not supported. |
| speed | string | No | `relax` (default, $0.045), `fast` ($0.055) or `turbo` ($0.10). --relax / --fast / --turbo in the prompt work too; this field wins. |
| images | array | No | Image prompts, up to 5, as image URLs, data: URIs or base64; they go in front of the prompt, as in Midjourney (use --iw to weight them). With action blend: the 2-5 images to blend. |
| size | string | No | A ratio (e.g. `3:2`) or a pixel size; turned into --ar when the prompt has none (an --ar in the prompt wins). An edit with neither keeps the image's own ratio. |
| task_id | string | No | The job to continue (img_..., finished, within 7 days). |
| action | string | No | `upscale` (2x, mode subtle / creative), `vary` (strength strong / subtle), `remix` (a new prompt), `reroll`, `zoom` (zoom out 1-2), `pan` (direction), `inpaint` (mask); and, without task_id, `blend` (2-5 images) and `edit` (one image plus an instruction). |
| index | integer | No | Which picture (1-4); optional on a single upscaled picture. |
| n | integer | No | Must be 1: one job is one set of four pictures, billed once. |
| callback_url | string | No | Where to push the result when the job ends; see Webhooks below. |

## Actions (task_id + action)

Continue a finished job (within 7 days), one action per button of the official app; the result is a new job, billed at the chosen speed.

| action | Fields | What it does |
| --- | --- | --- |
| upscale | index, mode | 2x upscale: mode `subtle` (default, keeps the details) or `creative` (adds detail); one picture back. |
| vary | index, strength | Four variations of picture index: strength `strong` (default) or `subtle`. |
| remix | index, prompt, strength | Keeps the composition and reshapes it to the new prompt; four pictures. |
| reroll | — | Runs the whole set again with the same prompt; four pictures. |
| zoom | index, zoom | Zooms out: zoom 1-2 (default 2); four pictures. |
| pan | index, direction | Extends left / right / up / down; four pictures. |
| inpaint | index, mask, prompt | Redraws only the white (or transparent) area of the mask; a mask in the picture's ratio is scaled to its size. Available when the job's actions list inpaint. |
| blend | images (2-5) | Without task_id: blends 2-5 images into a set of four; put the ratio in prompt (e.g. `--ar 3:2`). |
| edit | image, prompt | Without task_id: one image and a sentence saying what to change (V8.2 / 8.1); four pictures in the image's own ratio, unless the prompt has --ar or you pass size. |

## Price

Billed per job, a set of four pictures (one for an upscale); actions cost the same as a job at the chosen speed. --hd (V8 family) is 2x and a V7 --draft half price (rounded down to whole credits); varying or rerolling an HD set is 2x too. Held at submit, released in full on failure.

| Speed | Credits per image | USD per image |
| --- | --- | --- |
| relax (default) | 9 | $0.045 |
| fast | 11 | $0.055 |
| turbo | 20 | $0.10 |

## Sizes, versions and limits

- You get the PNG originals Midjourney made (with the content metadata Midjourney writes into them), never cropped or resized. The size follows the ratio: 1:1 is 1024×1024, 3:2 is 1344×896, 16:9 is 1456×816; --hd and upscale are 2x.

- Versions: V8.2 when none is written; --v 8.1 / 8 / 7 / 6.1 / 6 or --niji 7 / 6. --hd is for the V8 family only, --draft for V7 and V8 only (a V8 draft bills in full and can come back as 24 pictures).

- --repeat / --r and {a, b} permutations (one request becoming several jobs) are not supported; n must be 1.

- Up to 5 image prompts, placed in front of the prompt as in Midjourney (weight them with --iw); style references go in --sref <image URL>, V7 omni references in --oref <image URL>.

- Results and uploaded images are kept for 7 days; jobs older than that can no longer be continued.

- Describe (image to prompt) and Midjourney video are not available yet.

## Job status and fields

`GET /v1/images/jobs/{id}` reports these statuses; every field is described in [Async jobs](https://docs.kovapi.com/guide/async-jobs#fields). Poll every 2–3 seconds, or use a webhook.

| Status | Meaning |
| --- | --- |
| queued | Waiting in line. Carries `queue_position` (jobs ahead of yours) and `eta_seconds` (expected wait). |
| processing | Rendering. |
| succeeded | Done. The result is in `data[0].url`, the billing detail in `usage`. |
| failed | Failed. The reason is in `error`; the credits held for the job are refunded in full. |

One account runs up to 50 jobs at a time; further jobs wait in submission order, and a job that has not started after 15 minutes fails and is refunded in full. Job records are kept for 3 days and image links for 7 days.

## How long it takes

Measured on 11-21: four pictures took about 1.5-2 minutes on relax and fast, about 1.5 on turbo; an upscale about 2 minutes, zoom and pan about 1.3; image prompts or blend about 4. Peaks can be slower.

## Errors and refunds

An error at submit comes back at once as HTTP 4xx / 5xx: no job is created and nothing is charged. A failure after the job was accepted is reported by the job endpoint, and the hold is refunded in full. Every code is listed under [Error codes](https://docs.kovapi.com/guide/errors).

### Errors at submit

| HTTP | code | Cause | What to do |
| --- | --- | --- | --- |
| 400 | invalid_request | A reference image cannot be read (dead link, not an image, over 16MB...; `message` says which one and why), `/v1/images/edits` has no reference image, the body is not a JSON object, or `n` is not an integer. | Fix what `message` says and submit again. |
| 400 | unsupported_action | A reference image cannot be read (dead link, not an image, over 16MB...; `message` says which one and why), `/v1/images/edits` has no reference image, the body is not a JSON object, or `n` is not an integer. | Fix what `message` says and submit again. |
| 404 | task_not_found | A reference image cannot be read (dead link, not an image, over 16MB...; `message` says which one and why), `/v1/images/edits` has no reference image, the body is not a JSON object, or `n` is not an integer. | Fix what `message` says and submit again. |
| 401 | invalid_api_key | The key does not exist, was deleted or is disabled, or the account is disabled. | Check the key on the API Keys page of the console. |
| 402 | insufficient_quota | Not enough balance to hold this request. The gateway holds the highest possible cost of the request first, so a burst of concurrent calls can trigger it too. | After a burst, wait a few seconds and retry; otherwise top up. |
| 429 | rate_limit_exceeded | Over the requests-per-minute limit set on this key (counted over the last 60 seconds). No `Retry-After` header. | Wait a few seconds and retry, or raise the key's limit in the console. |
| 503 | service_unavailable | A temporary failure on our side, such as storing a reference file; `/v1/responses` also answers 503, with `Retry-After`, when it cannot take requests for a moment. | Retry shortly. |

### Failed jobs (`status` `failed`)

| code | When you see it | What to do |
| --- | --- | --- |
| moderation_blocked | Image: the model provider's safety system refused the prompt or a reference image (the code may also be `content_policy_violation`). | Rewrite the prompt or replace the reference; resubmitting it unchanged is usually refused again. |
| upstream_error | Any other failure: the automatic retries did not help, the job waited 15 minutes without starting, the upstream refused without a reason, and so on; `message` says which. | Submitting again usually works. |

## Webhooks instead of polling

Add `callback_url` when you submit and the moment the job ends, success or failure, the gateway pushes exactly what the poll endpoint returns to that URL, signed and retried on failure. You can also set an account-wide address under Settings → Webhook in the console. [Webhook docs →](https://docs.kovapi.com/webhooks)

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "midjourney", "prompt": "a red fox sitting in a snowy birch forest at dawn, soft golden light, 35mm film photograph --ar 3:2 --v 8.2", "callback_url": "https://your-domain.com/webhook"}'
```
