Skip to main content
Each way to create a task is its own endpoint, POST /midjourney/{endpoint}; every operation on an existing image goes through POST /midjourney/action, with action saying what to do. Both return a task ID, and GET /midjourney/task/{task_id} returns the result. If you haven’t made a call yet, start with the Quickstart.

​
All endpoints

Every endpoint accepts notify_hook (a URL we POST the result to when the task finishes). Every endpoint except describe accepts speed (relax / fast / turbo, default fast).

​
Generate

​
Work on existing images

Call POST /midjourney/action with action set to one of the values below, plus task_id (the task to build on). Operations that act on one image also take index: which image, starting at 1. It can be omitted when the task has a single image.
Without prompt, zoom, pan, and inpaint reuse the original task’s prompt. If you pass a prompt without a version, the original task’s version is added.

​
Video

To start from your own image, call POST /midjourney/video. Starting from an image in a task and extending a video are operations on existing tasks, so they go through POST /midjourney/action. See Video below for the parameters.

​
Follow-up operations

actions in the fetch result lists the operations you can run next on that task (the values action accepts on /midjourney/action). The rules match the Midjourney web app: Some images have extra limits:
  • V8 HD images (--hd) can’t be upscaled. Zoom, pan, and inpaint on them render at standard resolution.
  • V8.1 / V8.2 drafts sometimes come back as a batch of 24 images. A draft batch can only be varied, remixed, enhanced, or rerolled.
  • V8 (--v 8) can only be varied, remixed, animated, or rerolled.
Also:
  • You can only build on tasks in your own account that have succeeded. Submitting against an unfinished task returns task_not_finished.
  • index starts at 1 and goes up to the number of images (or videos, for a video task).
  • If an image fails content review, its slot in images is an empty string. The other images keep their numbers, and that image can’t be used further.
  • Videos can’t be rerolled. To try again, call video with the same parameters.

​
Prompt parameters

The prompt goes to Midjourney as written, so the parameters you use in Midjourney work here too: --ar, --v, --niji, --s, --c, --w, --q, --seed, --no, --sref, --oref, --cref, --iw, --p, --raw, --tile, --draft, --hd, and more. A few rules to know:
  • Speed: --relax, --fast, and --turbo are read as the speed parameter and not sent on. If both are present, the speed parameter wins.
  • Version: if no version is given, --v 8.2 (the current Midjourney default) is added.
  • Not supported: --repeat (--r) and permutation prompts {a, b}. They turn one request into several tasks; submit them separately.
  • Video parameters (--video, --motion, --bs, --loop, --end) only work on the video endpoints.
  • Reference images: image URLs in the prompt (image prompts at the start, and URLs after --sref, --cref, --oref) must be publicly downloadable. Weights after a URL (such as ::2) aren’t supported and are removed.
  • Prompts can be up to 6000 characters (letters, spaces, punctuation and CJK characters each count as one). For V8 models, a prompt whose text (the part before the parameters) is under 1024 characters always works. Longer prompts are condensed automatically before generation: normal long descriptions usually work, but repetitive text may be rejected with a 400 The prompt is too long, shorten it to under 1024 characters and try again, and nothing is charged; shorten the text to under 1024 characters.

​
Image input

images, image, mask, and end_image accept a publicly downloadable image URL or base64 (with or without the data:image/png;base64, prefix).
  • PNG, JPEG, GIF, and WebP, up to 20 MB each.
  • URLs must be public. Private-network addresses and pages behind a login are refused.
Inpaint masks: a black-and-white image where white marks the area to repaint and black is kept. Transparent areas also count as repaint. The mask can be a different size; it’s stretched to the image, so keep the same aspect ratio. All-white and all-black masks are rejected; to repaint the whole image, use variation or remix.

​
Video

There are two ways to give the first frame:
  • A generated image: call POST /midjourney/action with action set to video, plus task_id + index.
  • Your own image: call POST /midjourney/video with image.
To extend, call POST /midjourney/action with action set to video-extend, the video task’s task_id, and which video (index). Extensions keep the original resolution and number of videos, add about 4 seconds each time, and can be done up to 4 times. Video doesn’t support relax.

​
Billing

Each call is billed once, and failed tasks are refunded. Each capability’s price for each speed is in the price table on its model page; the cases below multiply the price for the speed you use. Speed: already in the price table: relax is 0.4x the fast price and turbo is 2x. Video has no relax, and describe has no speed. Version and quality (imagine, blend, edit, retexture, and reroll): Working on existing images:
  • Variation, upscale, zoom, pan, and enhance on a draft render at full quality and are billed at 1x, with no draft discount.
  • Variation on a V8 HD image is 2x, and so is remix with --hd in the new prompt.
  • Zoom, pan, and inpaint are always 1x (they render at standard resolution on HD images).
  • A plain reroll keeps the original task’s multiplier; a reroll with a new prompt is priced by the new prompt.
Video: the prices on the model page are for 480p and one video. resolution 720p is 3.2x, and batch_size 2 or 4 is 2x or 4x. video-extend is priced by the original video’s resolution and number of videos.

​
Errors

Every error has this shape, and the HTTP status matches the error type:

​
FAQ

Yes. Existing integrations don’t need to change. For new integrations we recommend these endpoints: no more assembling a custom_id from buttons; call /midjourney/action with action, task_id, and index to work on an image; and speed is a request parameter instead of a token setting.
index starts at 1 and goes up to the number of images in the task (or videos, for a video task). An upscaled task has a single image, so use 1 or leave index out.
A set of four drafts can be upscaled directly and is billed at full quality. You can also enhance first to regenerate at full quality, then upscale the one you like. A V8.1 / V8.2 batch of 24 drafts can’t be upscaled; enhance it first.
V8 HD images (--hd) are already high resolution, and Midjourney doesn’t upscale them further. You can still vary, zoom, or animate them.
Yes. describe returns immediately with the text in descriptions (written in Chinese); pass it to imagine.