Midjourney API Reference

Version: v1.0
Last Updated: 2026-06-15
Base URL: https://cloud.dataeyes.ai
Authentication: Bearer Token

1. Overview

This API provides a wrapper around Midjourney's image generation capabilities, supporting the following core features:

Feature	Description
Imagine	Generate images from text prompts (2x2 grid)
Upscale (U1-U4)	Upscale a selected image from the grid to high resolution
Variation (V1-V4)	Generate variations based on a selected image from the grid
Reroll	Regenerate the 2x2 grid using the same prompt

2. Authentication & General Conventions

2.1 Request Headers

All requests must include the following headers:

Header	Required	Value	Description
`Authorization`	Yes	`Bearer {API_KEY}`	API Key authentication
`Content-Type`	Yes	`application/json`	Request body format
`User-Agent`	Yes	Any valid UA string	Required — requests without a User-Agent will be blocked by Cloudflare with a 403 response

2.2 Common Response Format

{
  "code": 1,
  "description": "Submitted successfully",
  "result": "Task ID",
  "properties": { ... }
}

Field	Type	Description
`code`	int	Status code. `1` indicates success; other values indicate failure
`description`	string	Status description message
`result`	string	Task ID (returned by submission endpoints)
`properties`	object	Additional information (queue count, instance ID, etc.)

3. API Endpoints

3.1 Submit Image Generation Task (Imagine)

Submit a Midjourney image generation task based on a text prompt.

Request

POST /mj/submit/imagine

Request Body

Field	Type	Required	Description
`prompt`	string	Yes	Midjourney prompt, supporting native parameters such as `--v 6.1`, `--ar 16:9`
`botType`	string	No	Bot type. Default: `MID_JOURNEY`. Optional: `NIJI_JOURNEY`
`accountFilter`	object	No	Account filter criteria
`accountFilter.modes`	string[]	No	Generation mode. Options: `FAST`, `RELAX`, `TURBO`

Request Example

Response Example

{
  "code": 1,
  "description": "Submitted successfully",
  "result": "1781524258075013",
  "properties": {
    "discordInstanceId": "273d9093c1c54b6b",
    "discordChannelId": "273d9093c1c54b6b"
  }
}

3.2 Query Task Status (Fetch)

Query the execution status, progress, and result of a specified task.

Request

GET /mj/task/{taskId}/fetch

Path Parameters

Parameter	Type	Description
`taskId`	string	Task ID returned when the task was submitted

Request Example

Response Example

{
  "id": "1781524258075013",
  "action": "IMAGINE",
  "prompt": "a futuristic cityscape at sunset --v 6.1",
  "promptEn": "a futuristic cityscape at sunset --v 6.1",
  "description": "Submitted successfully",
  "status": "SUCCESS",
  "progress": "100%",
  "submitTime": 1781524258075,
  "startTime": 1781524259689,
  "finishTime": 1781524294590,
  "imageUrl": "www.yourdomain.com/mj/image/1781524258075013",
  "failReason": "",
  "buttons": [
    {
      "customId": "MJ::JOB::upsample::1::675515df-961f-411e-8e9b-d81ac68427f5",
      "emoji": "",
      "label": "U1",
      "type": 2,
      "style": 2
    },
    {
      "customId": "MJ::JOB::reroll::0::675515df-961f-411e-8e9b-d81ac68427f5::SOLO",
      "emoji": "🔄",
      "label": "",
      "type": 2,
      "style": 2
    }
  ],
  "properties": {
    "finalPrompt": "a futuristic cityscape at sunset --v 6.1 --fast",
    "finalZhPrompt": ""
  }
}

Response Field Descriptions

Field	Type	Description
`id`	string	Unique task identifier
`action`	string	Task type: `IMAGINE`, `UPSCALE`, `VARIATION`, `REROLL`
`prompt`	string	Original prompt
`status`	string	Task status — see Task Status Enum
`progress`	string	Progress percentage, e.g., `0%`, `50%`, `100%`
`imageUrl`	string	Access path for the generated image (replace with actual domain prefix)
`failReason`	string	Failure reason (populated only on failure)
`buttons`	array	Available action list, containing button information for U1-U4, V1-V4, Reroll, etc.
`buttons[].customId`	string	Unique action identifier — must be passed verbatim when submitting an Action
`buttons[].label`	string	Button display text (U1, V2, etc.)
`submitTime`	int64	Submission timestamp (milliseconds)
`startTime`	int64	Execution start timestamp (milliseconds)
`finishTime`	int64	Completion timestamp (milliseconds)

3.3 Submit Action Task (Action)

Execute follow-up operations on a completed task (upscale, variation, reroll).

Request

POST /mj/submit/action

Request Body

Field	Type	Required	Description
`taskId`	string	Yes	Original task ID
`customId`	string	Yes	The complete `customId` obtained from the `buttons` array in the Fetch response. Do not manually construct this value

Important: The customId contains a unique UUID generated for each task and is not interchangeable between tasks. It must be copied verbatim from the buttons array in the Fetch response.

Request Example

Response Example

{
  "code": 1,
  "description": "Queued, 5 tasks ahead",
  "result": "1781524431429700",
  "properties": {
    "numberOfQueues": 5,
    "discordInstanceId": "273d9093c1c54b6b",
    "discordChannelId": "273d9093c1c54b6b"
  }
}

After an Action is submitted, a new task ID is returned. Poll the status using this new ID.

3.4 Retrieve Generated Image (Image)

Directly retrieve the image file generated by a task.

Request

GET /mj/image/{taskId}

Path Parameters

Parameter	Type	Description
`taskId`	string	Task ID

Request Example

Response: Binary image file (Content-Type: image/png)

4. Complete Workflow

┌─────────────────────────────────────────────────────────────────┐
│                    Midjourney API Workflow                       │
└─────────────────────────────────────────────────────────────────┘

  Step 1                Step 2                Step 3              Step 4
┌─────────┐     ┌──────────────────┐    ┌──────────────┐    ┌──────────────┐
│ Imagine  │────>│  Poll Fetch      │───>│  Get buttons  │───>│ Submit Action │
│ Submit   │     │  Wait for SUCCESS│    │  Extract      │    │ (Optional)   │
│ Task     │     │                  │    │  customId     │    │              │
└─────────┘     └──────────────────┘    └──────────────┘    └──────────────┘
     │                   │                      │                    │
     v                   v                      v                    v
  Returns taskId    Returns full task       buttons array        Returns new taskId
                    info with imageUrl      with customId           ─────┐
                                                                       │
                                                                       v
                                                               ┌──────────────┐
                                                               │ Poll new task │
                                                               │ Wait SUCCESS  │
                                                               └──────────────┘

Detailed Step-by-Step

Step 1 — Submit Image Generation Task

Send a prompt and receive a taskId (e.g., 1781524258075013).

Step 2 — Poll Task Status

Poll at 3–5 second intervals until status becomes SUCCESS (typically takes 30–120 seconds).

Recommended polling strategy:

Interval: 5 seconds initially, then every 3 seconds

Timeout: Maximum 5 minutes

Termination condition: status is SUCCESS or FAILURE

Step 3 — Extract Available Actions

Once the task is complete, the buttons array in the response contains all executable actions. Each button's customId is the required parameter for submitting an Action.

Step 4 — Submit Follow-up Action (Optional)

Pass the original taskId and the complete customId obtained from buttons. A new taskId is returned — poll again until completion.

5. customId Format Specification

The customId is dynamically generated by Midjourney and is unique to each task. Format:

5.1 Format Template

MJ::JOB::{action}::{index}::{uuid}[::SOLO]

Component	Description
`MJ::JOB`	Fixed prefix
`{action}`	Action type: `upsample`, `variation`, `reroll`
`{index}`	Action index: `1`-`4` corresponding to grid positions; `0` for reroll
`{uuid}`	Unique task identifier (UUID v4), different for each generation
`::SOLO`	Suffix present only for reroll operations

5.2 Practical Examples

Using task 1781524258075013 as an example, the Fetch response's buttons contain the following customIds:

Action	Label	customId
Upscale #1	U1	`MJ::JOB::upsample::1::675515df-961f-411e-8e9b-d81ac68427f5`
Upscale #2	U2	`MJ::JOB::upsample::2::675515df-961f-411e-8e9b-d81ac68427f5`
Upscale #3	U3	`MJ::JOB::upsample::3::675515df-961f-411e-8e9b-d81ac68427f5`
Upscale #4	U4	`MJ::JOB::upsample::4::675515df-961f-411e-8e9b-d81ac68427f5`
Reroll	🔄	`MJ::JOB::reroll::0::675515df-961f-411e-8e9b-d81ac68427f5::SOLO`
Variation #1	V1	`MJ::JOB::variation::1::675515df-961f-411e-8e9b-d81ac68427f5`
Variation #2	V2	`MJ::JOB::variation::2::675515df-961f-411e-8e9b-d81ac68427f5`
Variation #3	V3	`MJ::JOB::variation::3::675515df-961f-411e-8e9b-d81ac68427f5`
Variation #4	V4	`MJ::JOB::variation::4::675515df-961f-411e-8e9b-d81ac68427f5`

5.3 Grid Position Reference

┌─────────┬─────────┐
│  1 (U1) │  2 (U2) │
│  (V1)   │  (V2)   │
├─────────┼─────────┤
│  3 (U3) │  4 (U4) │
│  (V3)   │  (V4)   │
└─────────┴─────────┘

Reminder: Do not attempt to manually construct customIds. The UUID portion is generated server-side by Midjourney and must be obtained from the buttons array via the Fetch endpoint.

6. Task Status Enum

Status	Description	Terminal State
`NOT_START`	Not started	No
`SUBMITTED`	Submitted	No
`IN_PROGRESS`	In progress (check the `progress` field for percentage)	No
`SUCCESS`	Completed successfully	Yes
`FAILURE`	Failed (check `failReason` for details)	Yes

7. Error Codes

Code	Description	Cause & Resolution
`1`	Submitted successfully	Normal
`21`	Task already exists	Duplicate submission — use existing taskId to query
`22`	Queued	Queue is busy — waiting for execution
`23`	Queue is full	Retry later
`24`	Prompt contains sensitive content	Modify the prompt and retry
Other	See `description` field	Troubleshoot based on the description

8. Complete Code Examples

8.1 Python — Full Workflow

8.2 cURL — Full Workflow

9. FAQ

Q1: Can I manually construct a customId?

No. The UUID in the customId is dynamically generated server-side by Midjourney for each task — different tasks have different UUIDs. You must obtain the complete customId from the buttons array via the Fetch endpoint.

Q2: Why does my request return 403?

Check whether the User-Agent header is included. Cloudflare's front-end protection blocks requests without a User-Agent, returning 403 error code: 1010.

Q3: How long does a task typically take?

Operation	Estimated Duration
Imagine (2x2 grid)	30–120 seconds
Upscale	15–60 seconds
Variation	30–120 seconds
Reroll	30–120 seconds

Actual duration depends on queue length and selected mode (FAST/TURBO/RELAX).

Q4: What is `www.yourdomain.com` in imageUrl?

This is a placeholder domain. To retrieve the actual image, use the GET /mj/image/{taskId} endpoint — there is no need to parse the imageUrl field.

Q5: What are the differences between FAST / RELAX / TURBO modes?

Mode	Speed	Cost
`TURBO`	Fastest	High
`FAST`	Fast	Medium
`RELAX`	Slower (queued)	Low

End of Document

Midjourney API Reference

Table of Contents#

1. Overview#

2. Authentication & General Conventions#

2.1 Request Headers#

2.2 Common Response Format#

3. API Endpoints#

3.1 Submit Image Generation Task (Imagine)#

3.2 Query Task Status (Fetch)#

3.3 Submit Action Task (Action)#

3.4 Retrieve Generated Image (Image)#

4. Complete Workflow#

Detailed Step-by-Step#

5. customId Format Specification#

5.1 Format Template#

5.2 Practical Examples#

5.3 Grid Position Reference#

6. Task Status Enum#

7. Error Codes#

8. Complete Code Examples#

8.1 Python — Full Workflow#

8.2 cURL — Full Workflow#

9. FAQ#

Q1: Can I manually construct a customId?#

Q2: Why does my request return 403?#

Q3: How long does a task typically take?#

Q4: What is www.yourdomain.com in imageUrl?#

Q5: What are the differences between FAST / RELAX / TURBO modes?#

Table of Contents

1. Overview

2. Authentication & General Conventions

2.1 Request Headers

2.2 Common Response Format

3. API Endpoints

3.1 Submit Image Generation Task (Imagine)

3.2 Query Task Status (Fetch)

3.3 Submit Action Task (Action)

3.4 Retrieve Generated Image (Image)

4. Complete Workflow

Detailed Step-by-Step

5. customId Format Specification

5.1 Format Template

5.2 Practical Examples

5.3 Grid Position Reference

6. Task Status Enum

7. Error Codes

8. Complete Code Examples

8.1 Python — Full Workflow

8.2 cURL — Full Workflow

9. FAQ

Q1: Can I manually construct a customId?

Q2: Why does my request return 403?

Q3: How long does a task typically take?

Q4: What is `www.yourdomain.com` in imageUrl?

Q5: What are the differences between FAST / RELAX / TURBO modes?