OpenAI Images API

openapi: 3.0.0
info:
  title: 'OpenAI images'
  description: Needs description.
  version: 2.0.0
  termsOfService: https://openai.com/policies/terms-of-use
  contact:
    name: OpenAI Support
    url: https://help.openai.com/
  license:
    name: MIT
    url: https://github.com/openai/openai-openapi/blob/master/LICENSE
servers:
  - url: https://api.openai.com/v1
tags:
  - name: Images
    description: Given a prompt and/or an input image, the model will generate a new image.
paths:
  /images/generations:
    post:
      operationId: createImage
      tags:
        - Images
      summary: OpenAI Creates an image given a prompt.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateImageRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImagesResponse'
      x-oaiMeta:
        name: Create image
        group: images
        returns: Returns a list of [image](/docs/api-reference/images/object) objects.
        examples:
          request:
            curl: |
              curl https://api.openai.com/v1/images/generations \
                -H "Content-Type: application/json" \
                -H "Authorization: Bearer $OPENAI_API_KEY" \
                -d '{
                  "model": "dall-e-3",
                  "prompt": "A cute baby sea otter",
                  "n": 1,
                  "size": "1024x1024"
                }'
            python: |
              from openai import OpenAI
              client = OpenAI()

              client.images.generate(
                model="dall-e-3",
                prompt="A cute baby sea otter",
                n=1,
                size="1024x1024"
              )
            node.js: |-
              import OpenAI from "openai";

              const openai = new OpenAI();

              async function main() {
                const image = await openai.images.generate({ model: "dall-e-3", prompt: "A cute baby sea otter" });

                console.log(image.data);
              }
              main();
          response: |
            {
              "created": 1589478378,
              "data": [
                {
                  "url": "https://..."
                },
                {
                  "url": "https://..."
                }
              ]
            }
  /images/edits:
    post:
      operationId: createImageEdit
      tags:
        - Images
      summary: >-
        OpenAI Creates an edited or extended image given an original image and a prompt.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateImageEditRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImagesResponse'
      x-oaiMeta:
        name: Create image edit
        group: images
        returns: Returns a list of [image](/docs/api-reference/images/object) objects.
        examples:
          request:
            curl: |
              curl https://api.openai.com/v1/images/edits \
                -H "Authorization: Bearer $OPENAI_API_KEY" \
                -F image="@otter.png" \
                -F mask="@mask.png" \
                -F prompt="A cute baby sea otter wearing a beret" \
                -F n=2 \
                -F size="1024x1024"
            python: |
              from openai import OpenAI
              client = OpenAI()

              client.images.edit(
                image=open("otter.png", "rb"),
                mask=open("mask.png", "rb"),
                prompt="A cute baby sea otter wearing a beret",
                n=2,
                size="1024x1024"
              )
            node.js: |-
              import fs from "fs";
              import OpenAI from "openai";

              const openai = new OpenAI();

              async function main() {
                const image = await openai.images.edit({
                  image: fs.createReadStream("otter.png"),
                  mask: fs.createReadStream("mask.png"),
                  prompt: "A cute baby sea otter wearing a beret",
                });

                console.log(image.data);
              }
              main();
          response: |
            {
              "created": 1589478378,
              "data": [
                {
                  "url": "https://..."
                },
                {
                  "url": "https://..."
                }
              ]
            }
  /images/variations:
    post:
      operationId: createImageVariation
      tags:
        - Images
      summary: OpenAI Creates a variation of a given image.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateImageVariationRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImagesResponse'
      x-oaiMeta:
        name: Create image variation
        group: images
        returns: Returns a list of [image](/docs/api-reference/images/object) objects.
        examples:
          request:
            curl: |
              curl https://api.openai.com/v1/images/variations \
                -H "Authorization: Bearer $OPENAI_API_KEY" \
                -F image="@otter.png" \
                -F n=2 \
                -F size="1024x1024"
            python: |
              from openai import OpenAI
              client = OpenAI()

              response = client.images.create_variation(
                image=open("image_edit_original.png", "rb"),
                n=2,
                size="1024x1024"
              )
            node.js: |-
              import fs from "fs";
              import OpenAI from "openai";

              const openai = new OpenAI();

              async function main() {
                const image = await openai.images.createVariation({
                  image: fs.createReadStream("otter.png"),
                });

                console.log(image.data);
              }
              main();
          response: |
            {
              "created": 1589478378,
              "data": [
                {
                  "url": "https://..."
                },
                {
                  "url": "https://..."
                }
              ]
            }
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
  schemas:
    ImagesResponse:
      properties:
        created:
          type: integer
        data:
          type: array
          items:
            $ref: '#/components/schemas/Image'
      required:
        - created
        - data
security:
  - ApiKeyAuth: []
x-oaiMeta:
  groups:
    - id: audio
      title: Audio
      description: |
        Learn how to turn audio into text or text into audio.

        Related guide: [Speech to text](/docs/guides/speech-to-text)
      sections:
        - type: endpoint
          key: createSpeech
          path: createSpeech
        - type: endpoint
          key: createTranscription
          path: createTranscription
        - type: endpoint
          key: createTranslation
          path: createTranslation
    - id: chat
      title: Chat
      description: >
        Given a list of messages comprising a conversation, the model will
        return a response.


        Related guide: [Chat Completions](/docs/guides/text-generation)
      sections:
        - type: endpoint
          key: createChatCompletion
          path: create
        - type: object
          key: CreateChatCompletionResponse
          path: object
        - type: object
          key: CreateChatCompletionStreamResponse
          path: streaming
    - id: embeddings
      title: Embeddings
      description: >
        Get a vector representation of a given input that can be easily consumed
        by machine learning models and algorithms.


        Related guide: [Embeddings](/docs/guides/embeddings)
      sections:
        - type: endpoint
          key: createEmbedding
          path: create
        - type: object
          key: Embedding
          path: object
    - id: fine-tuning
      title: Fine-tuning
      description: >
        Manage fine-tuning jobs to tailor a model to your specific training
        data.


        Related guide: [Fine-tune models](/docs/guides/fine-tuning)
      sections:
        - type: endpoint
          key: createFineTuningJob
          path: create
        - type: endpoint
          key: listPaginatedFineTuningJobs
          path: list
        - type: endpoint
          key: listFineTuningEvents
          path: list-events
        - type: endpoint
          key: retrieveFineTuningJob
          path: retrieve
        - type: endpoint
          key: cancelFineTuningJob
          path: cancel
        - type: object
          key: FineTuningJob
          path: object
        - type: object
          key: FineTuningJobEvent
          path: event-object
    - id: files
      title: Files
      description: >
        Files are used to upload documents that can be used with features like
        [Assistants](/docs/api-reference/assistants) and
        [Fine-tuning](/docs/api-reference/fine-tuning).
      sections:
        - type: endpoint
          key: createFile
          path: create
        - type: endpoint
          key: listFiles
          path: list
        - type: endpoint
          key: retrieveFile
          path: retrieve
        - type: endpoint
          key: deleteFile
          path: delete
        - type: endpoint
          key: downloadFile
          path: retrieve-contents
        - type: object
          key: OpenAIFile
          path: object
    - id: images
      title: Images
      description: >
        Given a prompt and/or an input image, the model will generate a new
        image.


        Related guide: [Image generation](/docs/guides/images)
      sections:
        - type: endpoint
          key: createImage
          path: create
        - type: endpoint
          key: createImageEdit
          path: createEdit
        - type: endpoint
          key: createImageVariation
          path: createVariation
        - type: object
          key: Image
          path: object
    - id: models
      title: Models
      description: >
        List and describe the various models available in the API. You can refer
        to the [Models](/docs/models) documentation to understand what models
        are available and the differences between them.
      sections:
        - type: endpoint
          key: listModels
          path: list
        - type: endpoint
          key: retrieveModel
          path: retrieve
        - type: endpoint
          key: deleteModel
          path: delete
        - type: object
          key: Model
          path: object
    - id: moderations
      title: Moderations
      description: >
        Given a input text, outputs if the model classifies it as violating
        OpenAI's content policy.


        Related guide: [Moderations](/docs/guides/moderation)
      sections:
        - type: endpoint
          key: createModeration
          path: create
        - type: object
          key: CreateModerationResponse
          path: object
    - id: assistants
      title: Assistants
      beta: true
      description: |
        Build assistants that can call models and use tools to perform tasks.

        [Get started with the Assistants API](/docs/assistants)
      sections:
        - type: endpoint
          key: createAssistant
          path: createAssistant
        - type: endpoint
          key: createAssistantFile
          path: createAssistantFile
        - type: endpoint
          key: listAssistants
          path: listAssistants
        - type: endpoint
          key: listAssistantFiles
          path: listAssistantFiles
        - type: endpoint
          key: getAssistant
          path: getAssistant
        - type: endpoint
          key: getAssistantFile
          path: getAssistantFile
        - type: endpoint
          key: modifyAssistant
          path: modifyAssistant
        - type: endpoint
          key: deleteAssistant
          path: deleteAssistant
        - type: endpoint
          key: deleteAssistantFile
          path: deleteAssistantFile
        - type: object
          key: AssistantObject
          path: object
        - type: object
          key: AssistantFileObject
          path: file-object
    - id: threads
      title: Threads
      beta: true
      description: |
        Create threads that assistants can interact with.

        Related guide: [Assistants](/docs/assistants/overview)
      sections:
        - type: endpoint
          key: createThread
          path: createThread
        - type: endpoint
          key: getThread
          path: getThread
        - type: endpoint
          key: modifyThread
          path: modifyThread
        - type: endpoint
          key: deleteThread
          path: deleteThread
        - type: object
          key: ThreadObject
          path: object
    - id: messages
      title: Messages
      beta: true
      description: |
        Create messages within threads

        Related guide: [Assistants](/docs/assistants/overview)
      sections:
        - type: endpoint
          key: createMessage
          path: createMessage
        - type: endpoint
          key: listMessages
          path: listMessages
        - type: endpoint
          key: listMessageFiles
          path: listMessageFiles
        - type: endpoint
          key: getMessage
          path: getMessage
        - type: endpoint
          key: getMessageFile
          path: getMessageFile
        - type: endpoint
          key: modifyMessage
          path: modifyMessage
        - type: object
          key: MessageObject
          path: object
        - type: object
          key: MessageFileObject
          path: file-object
    - id: runs
      title: Runs
      beta: true
      description: |
        Represents an execution run on a thread.

        Related guide: [Assistants](/docs/assistants/overview)
      sections:
        - type: endpoint
          key: createRun
          path: createRun
        - type: endpoint
          key: createThreadAndRun
          path: createThreadAndRun
        - type: endpoint
          key: listRuns
          path: listRuns
        - type: endpoint
          key: listRunSteps
          path: listRunSteps
        - type: endpoint
          key: getRun
          path: getRun
        - type: endpoint
          key: getRunStep
          path: getRunStep
        - type: endpoint
          key: modifyRun
          path: modifyRun
        - type: endpoint
          key: submitToolOuputsToRun
          path: submitToolOutputs
        - type: endpoint
          key: cancelRun
          path: cancelRun
        - type: object
          key: RunObject
          path: object
        - type: object
          key: RunStepObject
          path: step-object
    - id: completions
      title: Completions
      legacy: true
      description: >
        Given a prompt, the model will return one or more predicted completions
        along with the probabilities of alternative tokens at each position.
        Most developer should use our [Chat Completions
        API](/docs/guides/text-generation/text-generation-models) to leverage
        our best and newest models. Most models that support the legacy
        Completions endpoint [will be shut off on January 4th,
        2024](/docs/deprecations/2023-07-06-gpt-and-embeddings).
      sections:
        - type: endpoint
          key: createCompletion
          path: create
        - type: object
          key: CreateCompletionResponse
          path: object