KovAPIKovAPI
POST https://kovapi.com/v1/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.

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
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)

JSON
{
  "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
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.

JSON
{
  "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
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)

Python
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

Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Create an API Key in the console to start.

Parameters

ParameterTypeRequiredDescription
modelstringYesModel ID, here midjourney.
promptstringNoThe 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.
speedstringNorelax (default, $0.045), fast ($0.055) or turbo ($0.10). --relax / --fast / --turbo in the prompt work too; this field wins.
imagesarrayNoImage 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.
sizestringNoA 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_idstringNoThe job to continue (img_..., finished, within 7 days).
actionstringNoupscale (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).
indexintegerNoWhich picture (1-4); optional on a single upscaled picture.
nintegerNoMust be 1: one job is one set of four pictures, billed once.
callback_urlstringNoWhere 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.

actionFieldsWhat it does
upscaleindex, mode2x upscale: mode subtle (default, keeps the details) or creative (adds detail); one picture back.
varyindex, strengthFour variations of picture index: strength strong (default) or subtle.
remixindex, prompt, strengthKeeps the composition and reshapes it to the new prompt; four pictures.
reroll—Runs the whole set again with the same prompt; four pictures.
zoomindex, zoomZooms out: zoom 1-2 (default 2); four pictures.
panindex, directionExtends left / right / up / down; four pictures.
inpaintindex, mask, promptRedraws 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.
blendimages (2-5)Without task_id: blends 2-5 images into a set of four; put the ratio in prompt (e.g. --ar 3:2).
editimage, promptWithout 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.

SpeedCredits per imageUSD per image
relax (default)9$0.045
fast11$0.055
turbo20$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.

StatusMeaning
queuedWaiting in line. Carries queue_position (jobs ahead of yours) and eta_seconds (expected wait).
processingRendering.
succeededDone. The result is in data[0].url, the billing detail in usage.
failedFailed. 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

HTTPcodeCauseWhat to do
400invalid_requestA 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.
400unsupported_actionA 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.
404task_not_foundA 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.
401invalid_api_keyThe 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.
402insufficient_quotaNot 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.
429rate_limit_exceededOver 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.
503service_unavailableA 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)

codeWhen you see itWhat to do
moderation_blockedImage: 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_errorAny 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 · callback_url
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"}'