Code examples

Midjourney API in Python

Updated November 4, 2026

Before you start

• An API key from UserAPI.ai (how to get it). The first 50 requests are free.
• A Discord account with a paid Midjourney plan, added in the dashboard. If you haven't done that yet, follow the first steps.
• Python 3.8 or newer, pip install requests (and httpx for the async example).

The examples read the key from the environment: export USERAPI_KEY=your-key.

How it works

Generation is asynchronous. A POST to a method like /midjourney/v2/imagine doesn't wait for the image. It returns a task hash straight away, and Midjourney does the work in the background.

There are two ways to get the result. You can ask GET /midjourney/v2/status?hash=… every few seconds, or you can pass webhook_url and we will POST the task to your server when it changes. Either way you get the same JSON. Most of our users poll: webhooks are set on about one task in five. Once status is done, result has the image URL and its size. That task's hash is what you pass to the next step (upscale, variation, zoom and so on).

Possible statuses:

Generate, upscale, save

imagine returns a grid of four pictures. The script waits for it, upscales picture number 2 and writes it to fox.png. Midjourney flags like --ar or --v are just part of the prompt.

import os
import time

import requests

API_BASE = "https://api.userapi.ai"
HEADERS = {
    "api-key": os.environ["USERAPI_KEY"],
    "Content-Type": "application/json",
}


def post(method: str, payload: dict) -> str:
    """Start a task and return its hash."""
    r = requests.post(f"{API_BASE}/midjourney/v2/{method}", json=payload, headers=HEADERS, timeout=30)
    r.raise_for_status()
    return r.json()["hash"]


def wait(task_hash: str, interval: float = 5, timeout: float = 600) -> dict:
    """Poll the status endpoint until the task is done or failed."""
    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/midjourney/v2/status", params={"hash": task_hash}, headers=HEADERS, timeout=30)
        r.raise_for_status()
        task = r.json()
        if task["status"] == "done":
            return task
        if task["status"] == "error":
            raise RuntimeError(f"task failed: {task.get('status_reason')} {task.get('prefilter_result')}")
        print(f"{task['status']} {task.get('progress') or 0}%")
        time.sleep(interval)
    raise TimeoutError(task_hash)


def download(url: str, path: str) -> None:
    with requests.get(url, stream=True, timeout=60) as r:
        r.raise_for_status()
        with open(path, "wb") as f:
            for chunk in r.iter_content(65536):
                f.write(chunk)


if __name__ == "__main__":
    # 1. Generate a grid of four images
    grid = wait(post("imagine", {"prompt": "a red fox in a snowy forest, cinematic light --ar 3:2"}))
    print("grid:", grid["result"]["url"])

    # 2. Upscale the second image of the grid
    upscaled = wait(post("upscale", {"hash": grid["hash"], "choice": 2}))

    # 3. Save it: Discord CDN links are not permanent storage
    download(upscaled["result"]["url"], "fox.png")
    print("saved fox.png")

post() starts a task and gives back its hash. wait() asks for the status until the task is done (or raises on error). For upscale you pass the grid's hash and the picture number, 1 to 4. Status calls are not billed.

Midjourney parameters in the prompt

The prompt goes to Midjourney exactly as you send it, so all parameters work the same way as in Discord: aspect ratio, version, style references, image prompts. For a sense of what people actually send, here is how often parameters appear in successful prompts through our API:

Prompts are long, too: the average is about 570 characters. Midjourney checks parameter combinations itself, so a conflict like --oref with --version 8.1 comes back as an error with its message in status_reason.

Webhook instead of polling (Flask)

If the code runs on a server, it is easier to let us call you. Add webhook_url when starting the task:

task_hash = post("imagine", {
    "prompt": "isometric cozy coffee shop, soft pastel colors",
    "webhook_url": "https://your-server.com/midjourney/webhook",
    "webhook_type": "result",  # or "progress" for every progress update
})

The body we POST is the same JSON as the status response. "result" means one call when the task is finished or failed, "progress" adds the intermediate updates. A minimal receiver:

from flask import Flask, request

app = Flask(__name__)


@app.post("/midjourney/webhook")
def midjourney_webhook():
    task = request.get_json()
    if task["status"] == "done":
        print(task["type"], task["hash"], task["result"]["url"])
    elif task["status"] == "error":
        print("failed:", task["hash"], task.get("status_reason"))
    else:
        print(task["hash"], task["status"], task.get("progress"))
    return "", 200

Several prompts in parallel

The work happens on Midjourney's side, so nothing stops you from starting a few tasks and waiting for all of them. With httpx and asyncio:

import asyncio
import os

import httpx

API_BASE = "https://api.userapi.ai/midjourney/v2"
HEADERS = {"api-key": os.environ["USERAPI_KEY"]}


async def generate(client: httpx.AsyncClient, prompt: str) -> str:
    r = await client.post(f"{API_BASE}/imagine", json={"prompt": prompt})
    r.raise_for_status()
    task_hash = r.json()["hash"]
    while True:
        await asyncio.sleep(5)
        task = (await client.get(f"{API_BASE}/status", params={"hash": task_hash})).json()
        if task["status"] == "done":
            return task["result"]["url"]
        if task["status"] == "error":
            raise RuntimeError(task.get("status_reason"))


async def main():
    prompts = ["a lighthouse at dawn", "a lighthouse at noon", "a lighthouse at night"]
    async with httpx.AsyncClient(headers=HEADERS, timeout=30) as client:
        urls = await asyncio.gather(*(generate(client, p) for p in prompts))
    for prompt, url in zip(prompts, urls):
        print(prompt, "->", url)


asyncio.run(main())

Errors

When a task ends with status: "error", the reason is in status_reason. Log it. Sending the same prompt again and again usually doesn't help. Midjourney's own messages are passed through as they are. These are the ones we see most often:

Before a prompt goes to Midjourney we run an eligibility check on it. If the prompt doesn't pass, the task is not sent and prefilter_result lists why: TOXICITY, SEVERE_TOXICITY, IDENTITY_ATTACK, INSULT, PROFANITY, THREAT, SEXUALLY_EXPLICIT, FLIRTATION. An empty array means the check passed. The check is there to help your Discord account last longer. If you really need to, it can be turned off for imagine with "is_disable_prefilter": true.

Result URLs point to Discord's CDN. Download the files you want to keep instead of storing the links.

If tasks stop going through, check the account itself: GET /discord/info?account_hash=… returns its status. tos means you need to open Discord and accept the Midjourney terms, and banned means the account was banned.

Other methods

They all work like imagine and upscale above: change the method name in post() and the payload. Parameters are in the documentation.