openapi: 3.0.0 info: title: OpenAI Assistants Images API description: The Assistants API allows you to build AI assistants within your own applications. An Assistant has instructions and can leverage models, tools, and knowledge to respond to user queries. The Assistants API currently supports three types of tools - Code Interpreter, Retrieval, and Function calling. In the future, we plan to release more OpenAI-built tools, and allow you to provide your own tools on our platform. 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 security: - ApiKeyAuth: [] 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 \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -d '{\n \"model\": \"dall-e-3\",\n \"prompt\": \"A cute baby sea otter\",\n \"n\": 1,\n \"size\": \"1024x1024\"\n }'\n" python: "from openai import OpenAI\nclient = OpenAI()\n\nclient.images.generate(\n model=\"dall-e-3\",\n prompt=\"A cute baby sea otter\",\n n=1,\n size=\"1024x1024\"\n)\n" node.js: "import OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const image = await openai.images.generate({ model: \"dall-e-3\", prompt: \"A cute baby sea otter\" });\n\n console.log(image.data);\n}\nmain();" response: "{\n \"created\": 1589478378,\n \"data\": [\n {\n \"url\": \"https://...\"\n },\n {\n \"url\": \"https://...\"\n }\n ]\n}\n" /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 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F image=\"@otter.png\" \\\n -F mask=\"@mask.png\" \\\n -F prompt=\"A cute baby sea otter wearing a beret\" \\\n -F n=2 \\\n -F size=\"1024x1024\"\n" python: "from openai import OpenAI\nclient = OpenAI()\n\nclient.images.edit(\n image=open(\"otter.png\", \"rb\"),\n mask=open(\"mask.png\", \"rb\"),\n prompt=\"A cute baby sea otter wearing a beret\",\n n=2,\n size=\"1024x1024\"\n)\n" node.js: "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const image = await openai.images.edit({\n image: fs.createReadStream(\"otter.png\"),\n mask: fs.createReadStream(\"mask.png\"),\n prompt: \"A cute baby sea otter wearing a beret\",\n });\n\n console.log(image.data);\n}\nmain();" response: "{\n \"created\": 1589478378,\n \"data\": [\n {\n \"url\": \"https://...\"\n },\n {\n \"url\": \"https://...\"\n }\n ]\n}\n" /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 \\\n -H \"Authorization: Bearer $OPENAI_API_KEY\" \\\n -F image=\"@otter.png\" \\\n -F n=2 \\\n -F size=\"1024x1024\"\n" python: "from openai import OpenAI\nclient = OpenAI()\n\nresponse = client.images.create_variation(\n image=open(\"image_edit_original.png\", \"rb\"),\n n=2,\n size=\"1024x1024\"\n)\n" node.js: "import fs from \"fs\";\nimport OpenAI from \"openai\";\n\nconst openai = new OpenAI();\n\nasync function main() {\n const image = await openai.images.createVariation({\n image: fs.createReadStream(\"otter.png\"),\n });\n\n console.log(image.data);\n}\nmain();" response: "{\n \"created\": 1589478378,\n \"data\": [\n {\n \"url\": \"https://...\"\n },\n {\n \"url\": \"https://...\"\n }\n ]\n}\n" components: schemas: CreateImageEditRequest: type: object required: - image - prompt properties: image: type: string format: binary description: The image to edit. Must be a valid PNG file, less than 4MB, and square. If mask is not provided, the image must have transparency which will be used as the mask. example: example_value prompt: type: string maxLength: 32000 description: A text description of the desired image(s). The maximum length is 1000 characters for DALL-E 2 and 32000 characters for gpt-image-1. example: example_value mask: type: string format: binary description: An additional image whose fully transparent areas indicate where the image should be edited. Must be a valid PNG file, less than 4MB, and have the same dimensions as image. example: example_value model: type: string default: dall-e-2 description: The model to use for image editing. examples: - dall-e-2 - gpt-image-1 n: type: integer minimum: 1 maximum: 10 default: 1 description: The number of images to generate. example: 10 size: type: string enum: - 256x256 - 512x512 - 1024x1024 - auto default: 1024x1024 description: The size of the generated images. example: 256x256 response_format: type: string enum: - url - b64_json default: url description: The format in which the generated images are returned. example: url user: type: string description: A unique identifier representing your end-user. example: example_value ImagesResponse: properties: created: type: integer data: type: array items: $ref: '#/components/schemas/Image' required: - created - data CreateImageVariationRequest: type: object required: - image properties: image: type: string format: binary description: The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square. example: example_value model: type: string default: dall-e-2 description: The model to use for image variation. Only DALL-E 2 is supported. example: example_value n: type: integer minimum: 1 maximum: 10 default: 1 description: The number of images to generate. example: 10 response_format: type: string enum: - url - b64_json default: url description: The format in which the generated images are returned. example: url size: type: string enum: - 256x256 - 512x512 - 1024x1024 default: 1024x1024 description: The size of the generated images. example: 256x256 user: type: string description: A unique identifier representing your end-user. example: example_value CreateImageRequest: type: object required: - prompt properties: prompt: type: string maxLength: 32000 description: A text description of the desired image(s). The maximum length is 1000 characters for DALL-E 2 and 32000 characters for gpt-image-1. example: example_value model: type: string default: dall-e-2 description: The model to use for image generation. Defaults to dall-e-2. examples: - dall-e-2 - dall-e-3 - gpt-image-1 n: type: integer minimum: 1 maximum: 10 default: 1 description: The number of images to generate. Must be between 1 and 10. For DALL-E 3, only n=1 is supported. example: 10 quality: type: string enum: - standard - hd - low - medium - high - auto default: auto description: The quality of the image. hd creates images with finer details and greater consistency. For gpt-image-1 use low, medium, high, or auto. example: standard response_format: type: string enum: - url - b64_json default: url description: The format in which the generated images are returned. Must be one of url or b64_json. URLs are only valid for 60 minutes. example: url size: type: string enum: - 256x256 - 512x512 - 1024x1024 - 1792x1024 - 1024x1792 - auto default: 1024x1024 description: The size of the generated images. Must be one of the supported sizes for the model being used. example: 256x256 style: type: string enum: - vivid - natural default: vivid description: The style of the generated images. Vivid generates hyper-real and dramatic images. Natural produces more natural, less hyper-real images. Only supported for DALL-E 3. example: vivid user: type: string description: A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. example: example_value Image: type: object properties: url: type: string format: uri description: The URL of the generated image, if response_format is url. The URL is valid for 60 minutes. example: https://www.example.com b64_json: type: string description: The base64-encoded JSON of the generated image, if response_format is b64_json. example: example_value revised_prompt: type: string description: The prompt that was used to generate the image, if there was any revision to the prompt. Only present for DALL-E 3 and gpt-image-1. example: example_value securitySchemes: ApiKeyAuth: type: http scheme: bearer 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