Midjourney

This reference describes the implemented API contract. Paid integration checks on October 18, 2026 completed imagine requests for all nine listed versions, V8.2 Raw on/off, HD, Draft, V7 Omni Reference, describe, grid selection, and V6.1 inpaint → modal. These checks do not certify every parameter combination or visual effect. V8.2 HD+Draft failed in two checks but remains available; a tested remix failed because its original execution context lacked capacity. Unsupported combinations return an error before submission. Failed requests are not charged.

Start with one image request

Set SEEDROUTER_API_KEY on your server. Submit once, save the returned public task ID, then poll that ID. The simplest request needs only model and prompt. Its default action is imagine and its default speed is fast.

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"midjourney-v8.2","prompt":"A red paper boat on a calm pond at sunrise"}'

Copy id from the response into TASK_ID. Keep calling GET until status is completed or failed:

TASK_ID='task_ID_FROM_THE_RESPONSE'
curl "https://api.seedrouter.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

Read completed images from output.data[].url. If a POST times out or its outcome is uncertain, check task history instead of repeating it. A poll timeout does not cancel the task or justify a second POST.

Runnable Python example

Download the complete Python submit-and-poll example. It uses only Python's standard library and saves the task ID to a local file. Save the JSON request above as request.json, then run:

python3 midjourney-v8-2.py submit request.json --state image-task.json
python3 midjourney-v8-2.py poll --state image-task.json

The submit command refuses to overwrite its state file. Resume a long-running task by running poll again with the same file. The script never retries POST automatically. Change the model and parameters in request.json using the version examples below; use a new state-file name only for an intentionally new generation.

Choose a model version

These tables describe the implemented API contract, based on the API services' own documented inputs and exclusions. A field listed in a general API parameter table is accepted where a compatible request can be executed; that does not establish its visual effect on every model version. Documented support and live verification are separate. The API never changes the requested version or silently upgrades Relax to Fast.

All nine versions accept Raw, tile, iw 0–3, one style-reference URL, and the common numeric controls below. Character/style/depth inputs listed in the general API table have not been proven effective on every version. Never substitute one reference type for another.

“Conditionally available” means the complete combination must be executable. V8 Draft, quality 4, Omni Reference and explicit profiles cannot satisfy nsfw_check: true; they require API or administrator access. V6 also cannot satisfy that additional check. V8 character/depth/quality inputs can be combined with the extra check, but cannot be combined with fields that require an incompatible request path. For example, V8 quality: 1 plus stop: 100 currently has no compatible execution path, even though each field is individually supported.

Defaults and common bounds

New generations default only action to imagine and speed to fast. Version and family come from model. Omitted generation fields remain omitted; a billing label of quality 1 does not insert quality into the image request. Explicit zero and false are preserved. All numeric parameters stay within ±9,007,199,254,740,991 as a JSON/JavaScript transport safeguard; this is not a claimed model-specific range.

Fractional seed, stylize, chaos, weird, cw, sw and stop values require a compatible request without nsfw_check: true. Whole-number sw values from 0–1,000 have wider availability; other finite style weights are supported only on narrower combinations. These distinctions come from API number/integer contracts, not inferred model capabilities.

Midjourney V8.2 and V8.1

Applies to midjourney-v8.2 and midjourney-v8.1. Standard generation supports Relax, Fast and Turbo. Quality is optional and accepts 0.25, 0.5, 1 or 2. Character reference (cref/cw), style reference (sref/sw) and depth reference (dref/dw) are documented inputs; their effect with each version is still to be verified. iw is 0–3.

HD is a definition switch, separate from an upscale action. HD + Turbo remains unavailable because its price is not configured. Fast HD has a compatible request path. Integer ratios no wider than 4:1 work across the available HD contracts; other positive ratios have narrower availability and need live verification. Draft has a Fast-only path with up to 24 image choices and cannot satisfy the extra content check. HD + Draft is a separate configured mode, still awaiting combination verification.

stop 10–100 and a nonempty personalization profile have a Fast-only path without the extra content check. That path does not accept quality or cref, so combining those fields fails before submission. style: "raw" is normalized to Raw; other style strings have a separate compatible path and are not assumed to be visually effective. oref/ow are unavailable on V8.

Explicit sd: true, sv, exp, and edit currently have no established execution contract. edit is not an alias for image prompts, inpaint, or modal. V8 variation, grid selection, reroll and remix depend on the parent's available actions. Real upscale mode semantics are unverified. Zoom and pan have narrower parent-dependent Fast paths without the extra content check; inpaint is unavailable.

Midjourney V7

Applies to midjourney-v7. Quality accepts 0.25, 0.5, 1, 2 or 4; quality 4 requires a non-Relax request without the extra content check. Character and depth references use a different compatible request path from Omni Reference. Ordinary image prompts use iw 0–3.

Omni Reference uses one oref URL and optional finite ow. ow requires the URL so the correct reference price can be determined. Quality 4 with Omni Reference is accepted by the documented contract. Omni Reference + Draft remains blocked because the combined price is unresolved, not because a model-level incompatibility has been established.

Draft is supported. hd: true is accepted only as a documented no-op on the compatible path: it leaves standard output unchanged and adds no HD charge. Stop and explicit profiles require a non-Relax request without the extra check. sv, exp, edit, and explicit sd: true remain unavailable. See the action matrix for parent-specific operations.

Midjourney V6.1, V6 and Niji 6

Applies to midjourney-v6.1, midjourney-v6, and niji-v6. Quality accepts 0.25, 0.5, 1, 2 or 4. iw accepts 0–3; character weight cw accepts 0–100. Character and style references each use one HTTP(S) URL. Stop accepts 10–100. No generation default is inferred from the selected version.

V6.1 and Niji 6 support Relax/Fast/Turbo and depth inputs on compatible requests; V6 has only Fast/Turbo generation, no depth input, integer ratios up to 14:1, and no extra content-check path. All three accept a nonempty profile on compatible non-Relax requests. Quality 4 and fractional numeric controls have narrower availability. hd: true is a standard-output no-op with no HD charge. Draft and Omni Reference are unavailable.

For Niji 6, a negative prompt cannot be combined with fields that need its alternate request path, such as quality 4 or a profile. V6.1 and Niji 6 can begin inpaint when a valid parent permits it; V6 cannot. V6 parent actions require Fast. Real upscales use subtle/creative, not V5's 2x/4x; available parent buttons remain authoritative.

Midjourney V5.2 and V5.1

Applies to midjourney-v5.2 and midjourney-v5.1. Both accept quality 0.25, 0.5, 1 or 2, iw 0–3, integer stop 10–100, character/style/depth references, Raw, tile and style strings. These inputs appear in the general API contract; version-specific visual effects remain unverified. Numeric controls documented as integers must be whole numbers here, including seed, stylize, chaos, weird, cw, sw and stop. Style weight is 0–1,000.

HD, Draft, Omni Reference, personalization and quality 4 have no current compatible path. Explicit sd: true, sv, exp, edit, repeat and prompt permutations are unavailable. Parent real upscales use 2x/4x and require the corresponding returned operation. They are distinct from free grid selection.

Niji 7

Applies to niji-v7. It has its own model ID and availability rules. Quality accepts 0.25, 0.5, 1 or 2, and image weight accepts 0–3. Character/style/depth references are listed in the general API input table; effects with Niji 7 remain to be verified. Numeric integer fields and style-weight bounds match the V5.1/V5.2 request path above.

Stop, quality 4, HD, Draft, Omni Reference and personalization have no current compatible path. Niji Draft output count and pricing have not been established. V8 remix is not an available Niji 7 action. Real upscale command semantics are unverified; grid selection and other actions still depend on a valid parent.

One valid generation example per model

These JSON bodies pass local model validation and have an implemented execution candidate. They are not records of paid success. Enable the model and its matching price before submitting. The examples deliberately set speed: "fast" for consistent cross-version use; omitting speed also uses Fast. Set speed: "relax" explicitly only when you want Relax and the version supports that path.

{"model":"midjourney-v8.2","prompt":"A red paper boat on a calm pond","speed":"fast","size":"16:9","raw":true,"hd":true}

More language examples

These examples show the request format for an enabled deployment. Keep API keys in server-side code.

curl https://api.seedrouter.ai/v1/images/generations \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "midjourney-v8.2",
    "prompt": "A red paper boat on a calm pond at sunrise, soft mist, no lettering",
    "speed": "fast",
    "size": "16:9",
    "raw": true
  }'

Endpoint and task result

Use POST https://api.seedrouter.ai/v1/images/generations with Authorization: Bearer YOUR_API_KEY and Content-Type: application/json. All image operations use this endpoint. The response contains an id, model, status: "processing", and created_at. Keep that ID and poll:

curl "https://api.seedrouter.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY"

A task has processing, completed, or failed status. Completed images are in output.data, as objects containing url and an optional one-based index. output.action identifies the operation; output.seed may be present. Describe results use output.text, an array of descriptions. An editing step may finish with output.awaiting_input: true and no images; submit a subsequent modal action using that task as its parent. Grid selection (upscale with mode: "select") has zero image-job usage because it retrieves an existing choice. Opening the input-only inpaint step also has zero usage; the final successful modal generation is charged once. A configured model price is still required. Image URLs point to delivered results. No monetary fields are returned.

When output.grid is true, one delivered file contains a grid of image choices; it is not expanded into individual image URLs. Parent actions can address the grid’s image positions even when output.data has one URL.

Neither a fixed number of descriptions nor English output is guaranteed. Display the returned text as supplied.

Do not assume every task has four images: ordinary generation usually yields four; a V8 draft set can contain 24; an upscale yields one; describe or an editing-input step can have no images. Read the returned array.

Generation parameters

Known fields do not accept null. Unknown JSON fields are discarded; unknown native flags are errors. This API uses URL references, public task IDs and polling, with no arbitrary image count or automatic batch expansion. Read the version and combination rules above in addition to this union table.

Recognized syntax with no current execution path

These fields remain visible so their status is explicit. They return an unavailable-combination error instead of being dropped, approximated or treated as already verified capabilities.

Native parameter translation

The order of precedence is structured field → extra → prompt suffix. This example uses a final aspect ratio of 16:9 and stylization of 80:

{
  "model": "midjourney-v8.2",
  "prompt": "A paper boat --ar 1:1 --s 50",
  "extra": "--ar 4:3 --s 80",
  "size": "16:9",
  "speed": "fast"
}

Aliases include --ar/--aspect → size, --s → stylize, --c → chaos, --w → weird, --q → quality, --no → negative_prompt, and --p → profile. --v and --niji must agree with the model ID. --fast, --relax and --turbo are speed switches. --raw, --tile, --draft, --hd and --sd take no value.

Conflicting aliases in a single source, such as --s 50 --stylize 80, are rejected. Boolean JSON false omits that switch; it does not become a literal native false argument. Ordinary quoted prose and URL query strings are preserved. Known control flags inside quotes, such as "--hd", "--q 2" or "--turbo", are rejected rather than allowed to bypass version, task-count or pricing checks. Structured string parameters also reject quoted embedded flags. Structured reference and negative-prompt fields cannot contain embedded --parameters. Ordinary :: prompt text is preserved. Compatibility still depends on the complete request; the API never rewrites a multiprompt into a different prompt.

Image actions and parent tasks

Use your returned SeedRouter parent_task_id, the same model, and an image index where required. Indices start at 1. Do not supply external task IDs, task_id, or private button IDs. A parent must belong to your account, remain usable, and have the required completed result. Its original generation context is preserved; expiration is checked before a child task starts.

A follow-up stays attached to its original task. If that task's original execution context is unavailable, expired or changed, the action is rejected or fails; the system does not transfer the task ID or recreate its parent elsewhere. This applies to variation, upscale, reroll, remix, zoom, pan, inpaint and modal continuations. Keep using each returned public task ID for the next supported step.

Action availability by version

Parent means an implemented path exists only if your completed parent exposes the corresponding action; it is not a guarantee that any image can use it. Conditional adds the restrictions below. No cell claims a paid action has passed live acceptance. All actions still require a configured price and the requested speed.

• Remix: V8 has a compatible parent-dependent operation. Other versions remain unavailable because the required parent execution mode and follow-up price have not both been established. A returned action hint alone does not establish a priced operation.
• Pan: V8 and V6 currently require Fast, explicit scale 1.1–3, and no extra nsfw_check: true. Other models may either accept the parent path's built-in scale or require explicit scale. A replacement prompt is supported only on the explicit-scale path.
• Prompt and ordinary parameter edits: compatible Fast parent contexts accept replacement text and ordinary generation parameters for variation, pan, and zoom. The same model version is retained. Other parent contexts accept only inherited settings. HD, Draft or Omni Reference overrides that change the billing mode remain unpriced and blocked; earlier-version HD no-ops do not add an HD charge. Parent identity and inherited parameters are checked by the owner-scoped quote. A Turbo parent is never silently billed as a Fast follow-up.
• Real upscale: V5 uses 2x/4x; other versions use subtle/creative. select only retrieves a grid choice and has zero image-job usage. An available Select operation does not establish a real upscale operation. V8 and Niji 7 real upscale command semantics remain unverified; their Select availability does not change that status.
• Inpaint → Modal: start inpaint with the parent and no mask, replacement prompt or generation-parameter overrides. When it returns awaiting_input: true, use its returned public task ID for modal, optionally adding prompt and mask_url. The input stage has zero jobs; a successful final modal generation is one charged job. A final modal with a mask is priced as inpainting, while a final modal without a mask is priced as outpainting. These price categories are derived from mask_url, not extra values you can pass in mode. V8 and V6 do not currently have this sequence.
• Describe: needs exactly one independent image URL and returns text. Available with Fast speed for V8.2, V8.1, V7, V6.1, V6 and Niji 6. Omit nsfw_check or use false; true, Relax and Turbo are unavailable. Describe requires API or administrator access because the signed-in form retains its additional content check. The selected model ID does not make Describe a generation in that image-model version. Incompatible combinations are rejected before submission; inputs are never silently changed.
• Blend: unavailable for every version because the current execution contract cannot preserve the selected version. Use imagine with a text description and image prompt URLs when that is the operation you intend; Blend is not automatically rewritten.

index ranges from 1 to the parent's available image choices, with a maximum of 24 for V8 draft and 4 for other versions. Some actions only support indices 1–4. Child actions do not accept image_urls; only imagine, blend and describe accept independent images. direction, scale, zoom_ratio and mask_url belong only to the actions described above.

{
  "model": "midjourney-v8.2",
  "action": "variation",
  "parent_task_id": "task_YOUR_COMPLETED_TASK",
  "index": 1,
  "mode": "subtle",
  "speed": "fast"
}

Reference images and editing masks

Use publicly accessible HTTP(S) URLs that return the image itself. For broad request compatibility, use PNG, JPEG or WebP files no larger than 12 MiB (12,582,912 bytes) each. These are documented image formats, not an exclusive format list. The 12 MiB limit applies to some supported requests, including their image prompts, reference images and editing masks; it is not a universal limit for every available model and request combination. Keeping each file within it avoids that size restriction when changing parameters.

For a supported modal request, mask_url must return a PNG mask: transparent areas are redrawn and white areas are preserved. Use the same dimensions as the parent image to avoid unintended alignment; this is preparation guidance, not an enforced universal dimension constraint. Start inpaint without a mask, then pass the mask in the subsequent modal request. The API does not convert between different mask conventions.

Submission checks reject a confirmed oversized file where the limit applies, a confirmed non-image response, or a confirmed non-PNG modal mask. A URL, filename suffix or successful quote alone does not prove that the remote image is readable or that its pixels form the intended mask. Files are not silently converted; inspect the image and mask before submitting. Other image formats and individual parameter effects remain subject to the supported request's behavior.

Errors and verification status

Invalid fields, version mismatches and unavailable combinations return an error before acceptance. A task accepted successfully can later fail; read its final status and error instead of resubmitting automatically. See the error reference for the public error format. Failed requests are not charged.

The October 18 paid checks established the output counts and completed workflows summarized at the top of this page. A completed operation does not guarantee that its images satisfy the prompt: the illustrated V6.1 masked edit returned images but did not show the requested clothing change. See the editing walkthrough. Other version/action combinations, individual reference effects and expiration boundaries still require separate verification. A local serializer or mocked test does not establish those results.

Contract scope

This reference defines SeedRouter's supported JSON and task contract, including the version-specific limits and request combinations listed above. The available API operations are assessed independently of the Midjourney website and Discord interface; a website feature does not establish API availability, and a website-only restriction is not automatically an API restriction. SeedRouter is not a Midjourney-operated API. Documented request support does not establish the visual effect of every parameter on every version; the remaining live checks are identified above.