Overview

Midjourney generative API based on mobile device simulation. Actively maintained for my own projects. Highly scalable. For extensive scaling needs, reach me out on Telegram @vasia972. Perfect for developers.

Content

• Jobs
• Imagine
• Blend
• Execute option
• Webhooks
• Examples

Jobs

The core of this API revolves around jobs. Each request instantiates a new job, initially set to a NEW status. As processing unfolds, this status gets updated.

Here’s the job structure returned upon request submission:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "NEW",
  "progress": 0,
  "result": "",
  "parent_id": null,
  "options": null,
  "error_message": null
}

1. id: Unique job identifier
2. status: Current job status (refer to the Statuses section)
3. progress: Generation progress (0-100%)
4. result: URL of the generated image.
5. parent_id: ID of the parent job (used with execute-option endpoint).
6. options: Available options list for the job.
7. error_message: Description of any job failures (refer to Errors section).

Flow

Typically, you’ll:

1. Submit a job.
2. Poll its ID till it reaches a final status.

Average processing times:

• Imagine: 30s - 2m
• Blend: 1 - 2m
• Upscale: 5 - 10s
• Others: 30s - 1m

Statuses

Status represent current job state. Returned data depends on the job status. See examples additionally to get a better understanding.

• NEW: Job queued for processing.
• PREPARING: Processing commenced; arguments under moderation.
• WAITING: Job dispatched to midjourney.
• IN_PROGRESS: Job currently underway.
• SUCCEEDED: Job completed successfully. FINAL status
• FAILED: Job faced issues. FINAL status

Status transitions

Errors

Potential errors and their contexts:

• OFFENSIVE_PROMPT (Imagine): the prompt you given may offense someone. Midjourney filters are pretty hard and unpredictable. Even the word ‘military’ may be banned in several contexts. I additionally moderate the prompts to filter extreme cases.
• FAILED_TO_DOWNLOAD_IMAGE (Blend): provided images are unreachable
• IMAGE_TOO_LARGE (Blend): Images exceed the 25MB limit
• INVALID_CONTENT_TYPE (Blend): Ensure submitted links are actual images
• OFFENSIVE_IMAGE (Blend): One/more images might be flagged. Midjourney’s image filters can be strict; even innocuous images might get flagged. I additionally moderate images to filter extreme cases.
• DUPLICATE_IMAGES (Blend): Identical images in the request
• SLOW_DOWN (Upsacle): Triggered when trying to upscale an image multiple times consecutively
• UNEXPECTED_ERROR Infrequent errors when midjourney doesn’t fulfill requests. Ensure to accommodate this unpredictable error in your error-handling strategy.
• INVALID_ARGUMENT[{RAW_DESCRIPTION}] (Imagine): Some of the parameters has invalid value. Examples may have contain markdown: INVALID_ARGUMENT[Invalid value provided for argument --stylize: ``invalid float value: '750,'``]. Let me know if you want it to have it different
• MIDJOURNEY_FAILED_TO_PROCESS_COMMAND (Imagine): Midjourney replies “failed to process your command :c”. Retry may help

Imagine

Create images with midjourney.

Submit your prompt to the designated endpoint to initiate image creation. Example request:

{
  "prompt": "women with black hair and glasses futurism style style of Carlo Carra dark blue background"
}

Upon successful completion, you’ll receive a response containing the generated image URL and available options for further actions:

• 0-3: Upsample 1st to 4th picture respectively.
• 4: Retry (though resubmitting the same prompt in a new request is advised over using this option).
• 5-8: Variations for the 1st to 4th picture respectively.

Intermediate results are accessible while the job is IN_PROGRESS.

Example result:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "SUCCEEDED",
  "progress": 100,
  "result": "https://cdn.discordapp.com/attachments/1163560386306523148/1163928244232400958/residentsleeperessence_women_with_black_hair_and_glasses_futuri_e793801b-5834-48b3-b064-4056faef96a7.png?ex=65415ba6&is=652ee6a6&hm=909e04a690dd30e984dded5d6832427e087cc275ed532900a35b1f57c1131730&",
  "parent_id": null,
  "options": ["U1", "U2", "U3", "U4", "🔄", "V1", "V2", "V3","V4"],
  "error_message": null
}

Blend

Blend images together seamlessly.

Example result for a man + golang logo (https://s.mj.run/7idgh2f1yDw, https://s.mj.run/_z2tqSb48so):

You would need to specify from 2 to 5 image urls for blend. The response will be a new job, following the standard flow.

Example request:

{
  "images": [
    "url_1", "url_2"
  ]
}

Execute option

To further refine or manipulate your generated image, use the Execute Option. Send a request specifying the option and the associated job. The response will be a new job, following the standard flow.

Example request:

{
  "option": 0,
  "parent_id": "00000000-0000-0000-0000-000000000000"
}

Note: This triggers the first option. Options are presented in the order provided by Midjourney, but some have been omitted. Delisted options include:

1. Vary (Region)
2. Cutsom Zoom
3. Like the job
4. Web

Webhooks

Webhooks provide a mechanism to get notifications about job status updates. When making requests to the generative API groups, simply include your webhook_url. Upon job status changes, our system will send updates to your specified callback URL in the form of a job object, consistent with the data structure of the GET job endpoint.

For every webhook received, your system should acknowledge with an HTTP status code 200. If your system responds with any other status code, I interpret it as a failure and will retry delivering the webhook based on the following schedule:

• First 12 attempts: 5-second delay between each attempt.
• Next 6 attempts: 30-second delay.
• Next 5 attempts: 1-minute delay.
• Next 6 attempts: 10-minute delay.
• Next 20 attempts: 30-minute delay.

Important Considerations

Overlapping Webhooks: If a job updates its status while a previous webhook is still in the delivery process, a new webhook will be generated. The previously undelivered webhook will be marked as ‘outdated’ and won’t be delivered anymore.

Temporary Results: Be aware that temporary images in the result field are transient. Once the job concludes, all temporary results become inaccessible. It is crucial to persist these results if they are of importance to your operations.

Order of Delivery: Webhooks might not always arrive in the order of events. We recommend implementing additional verification steps to ensure the correctness of the status and progress data when processing received webhooks.

Examples

Various job status examples:

New job

{
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "NEW",
  "progress": 0,
  "result": "",
  "parent_id": null,
  "options": null,
  "error_message": null
}

Job preparing

{
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "PREPARING",
  "progress": 0,
  "result": "",
  "parent_id": null,
  "options": null,
  "error_message": null
}

Job in progress

{
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "IN_PROGRESS",
  "progress": 31,
  "result": "",
  "parent_id": null,
  "options": null,
  "error_message": null
}

Job succeeded

{
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "SUCCEEDED",
  "progress": 100,
  "result": "https://cdn.discordapp.com/attachments/1165424365765132298/1166024434549805187/residentsleeperessence_mystic_blonde_portrait_c76e07bc-ec55-4370-8f87-69d539b28602.png?ex=6548fbe0&is=653686e0&hm=0fbcdd0e1750f765e87de702d90d9cf4f2c08931174e81bbd68b19314f11c12d&",
  "parent_id": null,
  "options": [
    "U1",
    "U2",
    "U3",
    "U4",
    "🔄",
    "V1",
    "V2",
    "V3",
    "V4"
  ],
  "error_message": null
}

Job failed

{
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "FAILED",
  "progress": 100,
  "result": "",
  "parent_id": null,
  "options": null,
  "error_message": "UNEXPECTED_ERROR"
}