openapi: 3.2.0
info:
  title: Midjourney Image Generation Image Analysis 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 Analysis
  description: Operations for analyzing existing images, including the describe endpoint that generates text prompts from uploaded images.
paths:
  /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'
components:
  schemas:
    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.
    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
    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.
  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/