openapi: 3.1.0
info:
title: Midjourney Image Generation API
description: >-
The Midjourney Image Generation API provides programmatic access to
Midjourney's AI-powered image generation capabilities. Developers can
submit text prompts to generate images, upscale selected outputs to
higher resolutions, create variations of generated images, describe
existing images to generate prompts, and blend multiple images together.
The API uses an asynchronous job-based workflow where image generation
requests return a job identifier that can be polled for status and
results. Webhook callbacks are supported for real-time job status
notifications. Enterprise API access is available through the Midjourney
Enterprise dashboard.
version: '1.0.0'
contact:
name: Midjourney Support
url: https://docs.midjourney.com/hc/en-us
termsOfService: https://docs.midjourney.com/hc/en-us/articles/32013317003661-Terms-of-Service
externalDocs:
description: Midjourney Documentation
url: https://docs.midjourney.com/
servers:
- url: https://api.midjourney.com
description: Midjourney Production API Server
tags:
- name: Image Analysis
description: >-
Operations for analyzing existing images, including the describe
endpoint that generates text prompts from uploaded images.
- name: Image Generation
description: >-
Operations for generating images from text prompts, including the
core imagine endpoint that produces a grid of images from a
natural language description.
- name: Image Manipulation
description: >-
Operations for manipulating existing generated images, including
upscaling to higher resolutions, creating variations, blending
multiple images, and region-based inpainting.
- name: Jobs
description: >-
Operations for tracking and managing asynchronous image generation
jobs, including retrieving job status, results, and listing
previous jobs.
security:
- bearerAuth: []
paths:
/v1/imagine:
post:
operationId: createImagineJob
summary: Generate images from a text prompt
description: >-
Submits a text prompt to generate a grid of up to four unique images
using Midjourney's AI models. The request is processed asynchronously
and returns a job identifier that can be used to poll for results or
receive updates via webhook. Supports parameters for aspect ratio,
model version, quality, stylization, and other generation settings
embedded in the prompt string or as separate parameters.
tags:
- Image Generation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ImagineRequest'
responses:
'200':
description: >-
Job successfully created. Returns a job identifier for tracking
the asynchronous image generation process.
content:
application/json:
schema:
$ref: '#/components/schemas/JobCreatedResponse'
'400':
description: >-
Invalid request. The prompt may be empty, contain blocked
content, or parameters may be malformed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: >-
Authentication failed. The API key is missing, invalid, or
expired.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: >-
Rate limit exceeded. Too many requests have been submitted
in the current time window.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/upscale:
post:
operationId: createUpscaleJob
summary: Upscale a generated image to higher resolution
description: >-
Upscales a specific image from a previously generated image grid
to a higher resolution. Requires the job identifier of the original
generation and the index of the image to upscale (1-4). The upscaled
image is produced asynchronously and the result can be retrieved via
the job status endpoint or webhook callback.
tags:
- Image Manipulation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpscaleRequest'
responses:
'200':
description: >-
Upscale job successfully created. Returns a new job identifier
for tracking the upscale operation.
content:
application/json:
schema:
$ref: '#/components/schemas/JobCreatedResponse'
'400':
description: >-
Invalid request. The parent job ID may be invalid or the
image index out of range.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: >-
Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: >-
The referenced parent job was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/variations:
post:
operationId: createVariationJob
summary: Create variations of a generated image
description: >-
Generates a new grid of image variations based on a specific image
from a previously generated grid. Requires the job identifier of the
original generation and the index of the image to vary (1-4). Each
variation maintains the general style and composition of the source
image while introducing creative differences.
tags:
- Image Manipulation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VariationRequest'
responses:
'200':
description: >-
Variation job successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/JobCreatedResponse'
'400':
description: >-
Invalid request.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: >-
Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: >-
The referenced parent job was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/describe:
post:
operationId: createDescribeJob
summary: Generate text prompts from an image
description: >-
Analyzes an uploaded image and generates multiple text prompt
suggestions that could be used to recreate a similar image with the
imagine endpoint. The image can be provided as a URL or base64-encoded
data. Returns up to four prompt suggestions per image.
tags:
- Image Analysis
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DescribeRequest'
responses:
'200':
description: >-
Describe job successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/JobCreatedResponse'
'400':
description: >-
Invalid request. The image URL may be inaccessible or the
base64 data malformed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: >-
Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/blend:
post:
operationId: createBlendJob
summary: Blend multiple images together
description: >-
Blends two to five images together to create a new composite image
that merges the visual concepts, styles, and compositions of the
source images. Images can be provided as URLs or base64-encoded data.
An optional text prompt can be included to guide the blending process.
tags:
- Image Manipulation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BlendRequest'
responses:
'200':
description: >-
Blend job successfully created.
content:
application/json:
schema:
$ref: '#/components/schemas/JobCreatedResponse'
'400':
description: >-
Invalid request. At least two images are required and no
more than five are allowed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: >-
Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/jobs/{jobId}:
get:
operationId: getJobStatus
summary: Get the status and results of a job
description: >-
Retrieves the current status, progress, and results of an
asynchronous image generation job. Returns the job metadata
including status, progress percentage, and when complete, the
URLs of the generated images. Poll this endpoint to track job
progress when webhooks are not configured.
tags:
- Jobs
parameters:
- $ref: '#/components/parameters/jobId'
responses:
'200':
description: >-
Job details retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'401':
description: >-
Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: >-
Job not found. The job ID may be invalid or the job may
have expired.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/jobs:
get:
operationId: listJobs
summary: List image generation jobs
description: >-
Retrieves a paginated list of image generation jobs for the
authenticated account. Jobs can be filtered by status and sorted
by creation date. Returns job metadata including status, prompts,
and result URLs for completed jobs.
tags:
- Jobs
parameters:
- name: status
in: query
description: >-
Filter jobs by their current status.
required: false
schema:
type: string
enum:
- pending
- in_progress
- completed
- failed
- cancelled
- name: limit
in: query
description: >-
Maximum number of jobs to return per page.
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 25
- name: offset
in: query
description: >-
Number of jobs to skip for pagination.
required: false
schema:
type: integer
minimum: 0
default: 0
- name: sort
in: query
description: >-
Sort order for the returned jobs.
required: false
schema:
type: string
enum:
- created_at_asc
- created_at_desc
default: created_at_desc
responses:
'200':
description: >-
List of jobs retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/JobListResponse'
'401':
description: >-
Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/jobs/{jobId}/cancel:
post:
operationId: cancelJob
summary: Cancel a pending or in-progress job
description: >-
Cancels a job that is currently pending or in progress. Jobs that
have already completed or failed cannot be cancelled. Cancelled
jobs do not consume generation credits.
tags:
- Jobs
parameters:
- $ref: '#/components/parameters/jobId'
responses:
'200':
description: >-
Job cancelled successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'400':
description: >-
Job cannot be cancelled because it has already completed
or failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: >-
Authentication failed.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: >-
Job not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: >-
API key obtained from the Midjourney Enterprise dashboard.
Include in the Authorization header as a Bearer token.
parameters:
jobId:
name: jobId
in: path
required: true
description: >-
The unique identifier of the image generation job.
schema:
type: string
format: uuid
schemas:
ImagineRequest:
type: object
required:
- prompt
properties:
prompt:
type: string
description: >-
The text prompt describing the image to generate. May include
Midjourney parameters such as --ar for aspect ratio, --v for
model version, --q for quality, and --s for stylization.
minLength: 1
maxLength: 4000
aspect_ratio:
type: string
description: >-
The aspect ratio for the generated images, expressed as
width:height. Common values include 1:1, 16:9, 9:16, 4:3,
and 3:2.
pattern: '^[0-9]+:[0-9]+$'
default: '1:1'
model_version:
type: string
description: >-
The Midjourney model version to use for generation.
enum:
- '5.2'
- '6.0'
- '6.1'
- '7.0'
process_mode:
type: string
description: >-
The processing speed mode for the generation job. Fast mode
uses GPU credits, turbo mode uses more credits for faster
results, and relax mode queues the job for processing during
low-demand periods.
enum:
- fast
- turbo
- relax
default: fast
quality:
type: number
description: >-
The quality setting for image generation. Higher values
produce more detailed images but consume more GPU time.
enum:
- 0.25
- 0.5
- 1.0
- 2.0
default: 1.0
stylize:
type: integer
description: >-
The stylization strength applied during generation. Lower
values produce images more closely matching the prompt,
while higher values apply more artistic interpretation.
minimum: 0
maximum: 1000
default: 100
chaos:
type: integer
description: >-
Controls the variation between the four generated images.
Higher values produce more diverse and unexpected results.
minimum: 0
maximum: 100
default: 0
seed:
type: integer
description: >-
A seed value for reproducible generation. Using the same
seed with the same prompt and settings produces similar
results.
minimum: 0
maximum: 4294967295
no:
type: string
description: >-
Negative prompt specifying elements to exclude from the
generated image.
image_url:
type: string
format: uri
description: >-
URL of a reference image to use as a starting point for
generation. The image influences the style and composition
of the output.
webhook_url:
type: string
format: uri
description: >-
URL to receive webhook notifications when the job status
changes. POST requests are sent with the job payload on
each status transition.
webhook_type:
type: string
description: >-
Controls when webhook notifications are sent. Use progress
for updates on each status change, or result to only receive
a notification upon completion or failure.
enum:
- progress
- result
default: result
UpscaleRequest:
type: object
required:
- job_id
- index
properties:
job_id:
type: string
format: uuid
description: >-
The job identifier of the original image generation job
containing the image to upscale.
index:
type: integer
description: >-
The index of the image in the generation grid to upscale,
from 1 (top-left) to 4 (bottom-right).
minimum: 1
maximum: 4
webhook_url:
type: string
format: uri
description: >-
URL to receive webhook notifications for this upscale job.
webhook_type:
type: string
description: >-
Controls when webhook notifications are sent.
enum:
- progress
- result
default: result
VariationRequest:
type: object
required:
- job_id
- index
properties:
job_id:
type: string
format: uuid
description: >-
The job identifier of the original image generation job
containing the image to create variations from.
index:
type: integer
description: >-
The index of the image in the generation grid to vary,
from 1 (top-left) to 4 (bottom-right).
minimum: 1
maximum: 4
webhook_url:
type: string
format: uri
description: >-
URL to receive webhook notifications for this variation job.
webhook_type:
type: string
description: >-
Controls when webhook notifications are sent.
enum:
- progress
- result
default: result
DescribeRequest:
type: object
properties:
image_url:
type: string
format: uri
description: >-
URL of the image to analyze and generate prompt suggestions
for. Either image_url or image_base64 must be provided.
image_base64:
type: string
format: byte
description: >-
Base64-encoded image data to analyze. Either image_url or
image_base64 must be provided.
webhook_url:
type: string
format: uri
description: >-
URL to receive webhook notifications for this describe job.
webhook_type:
type: string
description: >-
Controls when webhook notifications are sent.
enum:
- progress
- result
default: result
BlendRequest:
type: object
required:
- images
properties:
images:
type: array
description: >-
List of images to blend together. Between two and five images
can be provided, each as a URL or base64-encoded data.
minItems: 2
maxItems: 5
items:
type: object
properties:
url:
type: string
format: uri
description: >-
URL of the image to include in the blend.
base64:
type: string
format: byte
description: >-
Base64-encoded image data to include in the blend.
aspect_ratio:
type: string
description: >-
The aspect ratio for the blended output image.
pattern: '^[0-9]+:[0-9]+$'
default: '1:1'
prompt:
type: string
description: >-
Optional text prompt to guide the blending process.
maxLength: 4000
webhook_url:
type: string
format: uri
description: >-
URL to receive webhook notifications for this blend job.
webhook_type:
type: string
description: >-
Controls when webhook notifications are sent.
enum:
- progress
- result
default: result
Job:
type: object
properties:
id:
type: string
format: uuid
description: >-
The unique identifier for this job.
type:
type: string
description: >-
The type of image generation operation.
enum:
- imagine
- upscale
- variation
- describe
- blend
status:
type: string
description: >-
The current processing status of the job.
enum:
- pending
- in_progress
- completed
- failed
- cancelled
progress:
type: integer
description: >-
The completion progress as a percentage from 0 to 100.
minimum: 0
maximum: 100
prompt:
type: string
description: >-
The text prompt used for this generation job.
parameters:
type: object
description: >-
The generation parameters used for this job, including
aspect ratio, model version, and quality settings.
properties:
aspect_ratio:
type: string
description: >-
The aspect ratio used for generation.
model_version:
type: string
description: >-
The Midjourney model version used.
process_mode:
type: string
description: >-
The processing speed mode used.
quality:
type: number
description: >-
The quality setting used.
stylize:
type: integer
description: >-
The stylization value used.
seed:
type: integer
description: >-
The seed value used for generation.
result:
$ref: '#/components/schemas/JobResult'
error:
type: object
description: >-
Error details if the job failed.
properties:
code:
type: string
description: >-
Machine-readable error code.
message:
type: string
description: >-
Human-readable error description.
created_at:
type: string
format: date-time
description: >-
ISO 8601 timestamp when the job was created.
updated_at:
type: string
format: date-time
description: >-
ISO 8601 timestamp when the job was last updated.
completed_at:
type: string
format: date-time
description: >-
ISO 8601 timestamp when the job completed, if applicable.
JobResult:
type: object
description: >-
The output of a completed image generation job.
properties:
images:
type: array
description: >-
List of generated image URLs. For imagine jobs this contains
the grid image and individual image URLs. For upscale jobs
this contains the single upscaled image.
items:
$ref: '#/components/schemas/GeneratedImage'
prompts:
type: array
description: >-
List of generated prompt suggestions. Only present for
describe job results.
items:
type: string
GeneratedImage:
type: object
description: >-
A single generated image with its metadata.
properties:
url:
type: string
format: uri
description: >-
The URL where the generated image can be downloaded.
index:
type: integer
description: >-
The position of this image in the generation grid (1-4),
or null for grid and upscaled images.
minimum: 1
maximum: 4
width:
type: integer
description: >-
The width of the image in pixels.
height:
type: integer
description: >-
The height of the image in pixels.
content_type:
type: string
description: >-
The MIME type of the image file.
enum:
- image/png
- image/webp
JobCreatedResponse:
type: object
properties:
status:
type: string
description: >-
Indicates the request was accepted.
enum:
- SUCCESS
message:
type: string
description: >-
A human-readable message confirming job creation.
data:
type: object
properties:
job_id:
type: string
format: uuid
description: >-
The unique identifier assigned to the created job.
Use this ID to poll for status or receive webhook
notifications.
JobListResponse:
type: object
properties:
data:
type: array
description: >-
List of jobs matching the query parameters.
items:
$ref: '#/components/schemas/Job'
total:
type: integer
description: >-
Total number of jobs matching the filter criteria.
limit:
type: integer
description: >-
The maximum number of results per page.
offset:
type: integer
description: >-
The offset used for pagination.
ErrorResponse:
type: object
properties:
status:
type: string
description: >-
Indicates the request failed.
enum:
- ERROR
code:
type: string
description: >-
Machine-readable error code identifying the type of error.
message:
type: string
description: >-
Human-readable description of the error.