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.
Try in Playground →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
Create an API Key in the console to start.
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. 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.
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 →
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"}'