openapi: 3.2.0
info:
  title: Midjourney Image Generation Image Manipulation API
  description: The Midjourney Image Generation API provides programmatic access to Midjourney's AI-powered image generation capabilities.
  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
servers:
- url: https://api.midjourney.com
  description: Midjourney Production API Server
security:
- bearerAuth: []
tags:
- name: Image Manipulation
  description: Operations for manipulating existing generated images, including upscaling to higher resolutions, creating variations, blending multiple images, and region-based inpainting.
paths:
  /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/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'
components:
  schemas:
    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
    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
    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.
    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
    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.
  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.
externalDocs:
  description: Midjourney Documentation
  url: https://docs.midjourney.com/