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