> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rixapi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Midjourney Capabilities and Parameters

> Every endpoint, prompt parameters, follow-up operations, and billing

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](https://docs.rixapi.com/docs/en/guides/midjourney-quickstart.md).

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

| Endpoint | What it does | Required | Optional |
| - | - | - | - |
| `imagine` | Generate four images from a prompt, optionally with image prompts | `prompt` (optional when only `images` are given) | `images` (image prompts, up to 5) |
| `blend` | Blend 2 to 5 images into new images | `images` | `prompt` (parameters only, e.g. `--ar 16:9`) |
| `describe` | Describe an image as a prompt, **returned immediately** | `image` | — |
| `edit` | Change an image with a text instruction, such as a new background or color. V8.1 and later only; prompts without a version use V8.2 | `image`, `prompt` | — |
| `retexture` | Keep the composition and structure, restyle materials and look per the prompt. Supports V7 and V6; prompts without a version use V7 | `image`, `prompt` | — |

### 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.

```json theme={null}
{ "action": "variation", "task_id": "mj-0cd1cef934d741b4ab3643ed25515a90", "index": 2, "strength": "subtle" }
```

| `action` | What it does | Required | Optional |
| - | - | - | - |
| `upscale` | Upscale one image to 2x | `task_id`, `index` | `type`: `subtle` (default, faithful) / `creative` (adds detail) |
| `variation` | Generate four variations of one image | `task_id`, `index` | `strength`: `strong` (default, more change) / `subtle` (less change) |
| `remix` | Regenerate from one image with a new prompt | `task_id`, `index`, `prompt` | `strength` |
| `reroll` | Run the whole task again | `task_id` | `prompt` (rerun with a new prompt; the original version is kept if it names none) |
| `zoom` | Zoom out, keeping the image in the middle | `task_id`, `index` | `zoom`: 1.0 to 2.0, default 2.0; `prompt` |
| `pan` | Extend the image in one direction | `task_id`, `index`, `direction` (`up` / `down` / `left` / `right`) | `prompt` |
| `inpaint` | Repaint only the region marked by a mask | `task_id`, `index`, `mask` | `prompt` (what to paint in that region) |
| `enhance` | Pick one draft and regenerate it at full quality | `task_id`, `index` | — |

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`.

| Call | What it does | Required | Optional |
| - | - | - | - |
| `POST /midjourney/video` | Turn your own image into a video of about 5 seconds | `image` | `prompt`, `resolution`, `motion`, `batch_size`, `end_image`, `loop` |
| `action`: `video` | Start from one image in a task | `task_id`, `index` | Same as above |
| `action`: `video-extend` | Extend a video by about 4 seconds | `task_id`, `index` (which video) | `prompt`, `motion` |

See [Video](#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:

| Task output | Can run next |
| - | - |
| A set of images (from `imagine`, `blend`, `variation`, `remix`, `reroll`, `zoom`, `pan`, `inpaint`, `enhance`, `edit`, `retexture`) | `upscale`, `variation`, `remix`, `zoom`, `pan`, `inpaint`, `video`, `reroll`, plus `enhance` for drafts |
| A single upscaled image (from `upscale`) | `variation`, `remix`, `zoom`, `video` |
| Videos (from `video`, `video-extend`) | `video-extend`, up to 4 times |
| Text (from `describe`) | None |

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`.

| Parameter | Values | Default |
| - | - | - |
| `prompt` | The motion and camera you want. Without it, a generated image reuses the original task's prompt, and your own image gets motion chosen automatically | — |
| `resolution` | `480p` / `720p` | `480p` |
| `motion` | `low` (gentle) / `high` (large movement) | `low` |
| `batch_size` | Videos per task: `1` / `2` / `4` | `1` |
| `end_image` | End frame; the video moves toward this image | — |
| `loop` | When `true`, first and last frames match for a seamless loop. Can't be combined with `end_image` | `false` |

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

| Case | Multiplier |
| - | - |
| V7 draft (`--draft`) | 0.5 |
| V8.1 / V8.2 draft (`--draft`) | Pre-charged at 1x; settled at 0.5x with the difference refunded when 4 images come back, 1x when 24 come back |
| V8 HD (`--hd`) | 2 |
| Everything else | 1 |

**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:

```json theme={null}
{ "error": { "code": "invalid_request", "message": "index must be between 1 and 4" } }
```

| HTTP | `code` | Meaning |
| - | - | - |
| 400 | `invalid_request` | A parameter is wrong; `message` says which |
| 400 | `unsupported_action` | This task doesn't allow that operation; check `actions` in the fetch result |
| 400 | `content_rejected` | The prompt or image failed content review; nothing is charged |
| 401 | `unauthorized` | The API key is missing or invalid |
| 402 / 403 | `insufficient_quota` | Not enough balance |
| 404 | `task_not_found` | The task doesn't exist or belongs to another account |
| 404 | `not_found` | The endpoint name is wrong |
| 409 | `task_not_finished` | The task you're building on hasn't succeeded yet |
| 429 | `rate_limited` / `queue_full` | Too many requests, or the generation queue is full; retry later |
| 5xx | `upstream_error` / `internal_error` | A server-side failure; safe to retry |

## FAQ

> [accordion] Do the /mj/submit/\* endpoints still work?
>
> 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.

> [accordion] Why does index say it's out of range?
>
> `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.

> [accordion] Can I upscale a draft (--draft) directly?
>
> 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.

> [accordion] Why doesn't an HD image list upscale in actions?
>
> V8 HD images (`--hd`) are already high resolution, and Midjourney doesn't upscale them further. You can still vary, zoom, or animate them.

> [accordion] Can I use the describe output as a prompt?
>
> Yes. `describe` returns immediately with the text in `descriptions` (written in Chinese); pass it to `imagine`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.