OpenAI Embeddings API

openapi: 3.2.0
info:
  title: Openai Embeddings API
  license:
    name: MIT
    url: https://github.com/openai/openai-openapi/blob/master/LICENSE
  termsOfService: https://openai.com/policies/terms-of-use
  version: '1.0'
  description: 'Operations tagged Embeddings across 3 of this provider''s published API definitions: embeddings-openapi-original.yml, openai-embeddings-openapi.yml, openai-openapi-master.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.openai.com/v1
tags:
- name: Embeddings
  description: Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms.
paths:
  /embeddings:
    post:
      operationId: createEmbedding
      tags:
      - Embeddings
      summary: OpenAI Creates an embedding vector representing the input text.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmbeddingRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEmbeddingResponse'
      x-oaiMeta:
        name: Create embeddings
        group: embeddings
        returns: A list of [embedding](/docs/api-reference/embeddings/object) objects.
        examples:
          request:
            curl: "curl https://api.openai.com/v1/embeddings \\\n  -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"input\": \"The food was delicious and the waiter...\",\n    \"model\": \"text-embedding-ada-002\",\n    \"encoding_format\": \"float\"\n  }'\n"
            python: "from openai import OpenAI\nclient = OpenAI()\n\nclient.embeddings.create(\n  model=\"text-embedding-ada-002\",\n  input=\"The food was delicious and the waiter...\",\n  encoding_format=\"float\"\n)\n"
            node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n  const embedding = await openai.embeddings.create({\n    model: \"text-embedding-ada-002\",\n    input: \"The quick brown fox jumped over the lazy dog\",\n    encoding_format: \"float\",\n  });\n\n  console.log(embedding);\n}\n\nmain();"
          response: "{\n  \"object\": \"list\",\n  \"data\": [\n    {\n      \"object\": \"embedding\",\n      \"embedding\": [\n        0.0023064255,\n        -0.009327292,\n        .... (1536 floats total for ada-002)\n        -0.0028842222,\n      ],\n      \"index\": 0\n    }\n  ],\n  \"model\": \"text-embedding-ada-002\",\n  \"usage\": {\n    \"prompt_tokens\": 8,\n    \"total_tokens\": 8\n  }\n}\n"
      security:
      - ApiKeyAuth: []
    servers:
    - url: https://api.openai.com/v1
components:
  schemas:
    CreateEmbeddingResponse:
      type: object
      properties:
        data:
          type: array
          description: The list of embeddings generated by the model.
          items:
            $ref: '#/components/schemas/Embedding'
        model:
          type: string
          description: The name of the model used to generate the embedding.
        object:
          type: string
          description: The object type, which is always "list".
          enum:
          - list
        usage:
          type: object
          description: The usage information for the request.
          properties:
            prompt_tokens:
              type: integer
              description: The number of tokens used by the prompt.
            total_tokens:
              type: integer
              description: The total number of tokens used by the request.
          required:
          - prompt_tokens
          - total_tokens
      required:
      - object
      - model
      - data
      - usage
    CreateEmbeddingResponse_2:
      type: object
      required:
      - object
      - data
      - model
      - usage
      properties:
        object:
          type: string
          enum:
          - list
          description: The object type, always list.
          example: list
        data:
          type: array
          description: The list of embedding objects.
          items:
            $ref: '#/components/schemas/Embedding'
          example: []
        model:
          type: string
          description: The name of the model used to generate the embedding.
          example: example_value
        usage:
          $ref: '#/components/schemas/EmbeddingUsage'
    Embedding:
      type: object
      required:
      - object
      - embedding
      - index
      properties:
        object:
          type: string
          enum:
          - embedding
          description: The object type, always embedding.
          example: embedding
        embedding:
          oneOf:
          - type: array
            description: The embedding vector as an array of floats. The length of the vector depends on the model and dimensions parameter.
            items:
              type: number
              format: float
          - type: string
            description: The embedding vector as a base64-encoded string when encoding_format is base64.
          example: example_value
        index:
          type: integer
          description: The index of the embedding in the list of embeddings, corresponding to the position of the input.
          example: 10
    CreateEmbeddingRequest:
      type: object
      required:
      - model
      - input
      properties:
        model:
          type: string
          description: ID of the model to use. You can use the List Models API to see all available models, or see the Model overview for descriptions.
          examples:
          - text-embedding-3-small
          - text-embedding-3-large
          - text-embedding-ada-002
        input:
          oneOf:
          - type: string
            description: The string to embed.
          - type: array
            description: The array of strings to embed.
            items:
              type: string
            minItems: 1
            maxItems: 2048
          - type: array
            description: The array of integers (token IDs) to embed. Each array must have 8191 or fewer elements.
            items:
              type: integer
            minItems: 1
          - type: array
            description: The array of arrays containing integers (token IDs) to embed.
            items:
              type: array
              items:
                type: integer
              minItems: 1
            minItems: 1
          description: Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or array of token arrays. The input must not exceed the max input tokens for the model.
          example: example_value
        encoding_format:
          type: string
          enum:
          - float
          - base64
          default: float
          description: The format to return the embeddings in. Can be either float or base64. Defaults to float.
          example: float
        dimensions:
          type: integer
          minimum: 1
          description: The number of dimensions the resulting output embeddings should have. Only supported in text-embedding-3 and later models.
          example: 10
        user:
          type: string
          description: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.
          example: example_value
    EmbeddingUsage:
      type: object
      required:
      - prompt_tokens
      - total_tokens
      properties:
        prompt_tokens:
          type: integer
          description: The number of tokens in the input.
          example: 10
        total_tokens:
          type: integer
          description: The total number of tokens used.
          example: 10
    CreateEmbeddingResponse_3:
      type: object
      properties:
        data:
          type: array
          description: The list of embeddings generated by the model.
          items:
            $ref: '#/components/schemas/Embedding_2'
        model:
          type: string
          description: The name of the model used to generate the embedding.
        object:
          type: string
          description: The object type, which is always "list".
          enum:
          - list
          x-stainless-const: true
        usage:
          type: object
          description: The usage information for the request.
          properties:
            prompt_tokens:
              type: integer
              description: The number of tokens used by the prompt.
            total_tokens:
              type: integer
              description: The total number of tokens used by the request.
          required:
          - prompt_tokens
          - total_tokens
      required:
      - object
      - model
      - data
      - usage
    Embedding_2:
      type: object
      description: 'Represents an embedding vector returned by embedding endpoint.

        '
      properties:
        index:
          type: integer
          description: The index of the embedding in the list of embeddings.
        embedding:
          type: array
          description: 'The embedding vector, which is a list of floats. The length of vector depends on the model as listed in the [embedding guide](/docs/guides/embeddings).

            '
          items:
            type: number
            format: float
        object:
          type: string
          description: The object type, which is always "embedding".
          enum:
          - embedding
          x-stainless-const: true
      required:
      - index
      - object
      - embedding
      x-oaiMeta:
        name: The embedding object
        example: "{\n  \"object\": \"embedding\",\n  \"embedding\": [\n    0.0023064255,\n    -0.009327292,\n    .... (1536 floats total for ada-002)\n    -0.0028842222,\n  ],\n  \"index\": 0\n}\n"
    CreateEmbeddingRequest_2:
      type: object
      additionalProperties: false
      properties:
        input:
          description: 'Input text to embed, encoded as a string or array of tokens. To embed multiple inputs in a single request, pass an array of strings or array of token arrays. The input must not exceed the max input tokens for the model (8192 tokens for all embedding models), cannot be an empty string, and any array must be 2048 dimensions or less. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens. In addition to the per-input token limit, all embedding  models enforce a maximum of 300,000 tokens summed across all inputs in a  single request.

            '
          example: The quick brown fox jumped over the lazy dog
          oneOf:
          - type: string
            title: string
            description: The string that will be turned into an embedding.
            default: ''
            example: This is a test.
          - type: array
            title: array
            description: The array of strings that will be turned into an embedding.
            minItems: 1
            maxItems: 2048
            items:
              type: string
              default: ''
              example: '[''This is a test.'']'
          - type: array
            title: array
            description: The array of integers that will be turned into an embedding.
            minItems: 1
            maxItems: 2048
            items:
              type: integer
            example: '[1212, 318, 257, 1332, 13]'
          - type: array
            title: array
            description: The array of arrays containing integers that will be turned into an embedding.
            minItems: 1
            maxItems: 2048
            items:
              type: array
              minItems: 1
              items:
                type: integer
            example: '[[1212, 318, 257, 1332, 13]]'
        model:
          description: 'ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them.

            '
          example: text-embedding-3-small
          anyOf:
          - type: string
          - type: string
            enum:
            - text-embedding-ada-002
            - text-embedding-3-small
            - text-embedding-3-large
          x-oaiTypeLabel: string
        encoding_format:
          description: The format to return the embeddings in. Can be either `float` or [`base64`](https://pypi.org/project/pybase64/).
          example: float
          default: float
          type: string
          enum:
          - float
          - base64
        dimensions:
          description: 'The number of dimensions the resulting output embeddings should have. Only supported in `text-embedding-3` and later models.

            '
          type: integer
          minimum: 1
        user:
          type: string
          example: user-1234
          description: 'A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. [Learn more](/docs/guides/safety-best-practices#end-user-ids).

            '
      required:
      - model
      - input
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'OpenAI API key. Obtain from https://platform.openai.com/api-keys. Pass as Authorization: Bearer YOUR_API_KEY.'
    AdminApiKeyAuth:
      type: http
      scheme: bearer
x-refined-from:
- embeddings-openapi-original.yml
- openai-embeddings-openapi.yml
- openai-openapi-master.yml
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