OpenAI API

Giới thiệu

Bạn có thể tương tác với API thông qua các yêu cầu HTTP từ bất kỳ ngôn ngữ nào, thông qua các ràng buộc Python chính thức của chúng tôi, thư viện Node.js chính thức của chúng tôi hoặc thư viện do cộng đồng duy trì.

Để cài đặt các ràng buộc Python chính thức, hãy chạy lệnh sau:

Để cài đặt thư viện Node.js chính thức, hãy chạy lệnh sau trong thư mục dự án Node.js của bạn:

npm install openai@^4.0.0

Xác thực

Khóa API

API OpenAI sử dụng khóa API để xác thực. Bạn có thể tạo khóa API ở cấp tài khoản người dùng hoặc dịch vụ. Tài khoản dịch vụ được gắn với một cá nhân "bot" và nên được sử dụng để cung cấp quyền truy cập cho các hệ thống sản xuất. Mỗi khóa API có thể được giới hạn theo một trong những điều sau,

Khóa dự án - Cung cấp quyền truy cập vào một dự án duy nhất (tùy chọn ưu tiên); truy cập khóa API dự án bằng cách chọn dự án cụ thể mà bạn muốn tạo khóa.
Khóa người dùng - Khóa kế thừa của chúng tôi. Cung cấp quyền truy cập vào tất cả các tổ chức và tất cả các dự án mà người dùng đã được thêm vào; truy cập Khóa API để xem các khóa có sẵn của bạn. Chúng tôi khuyên bạn nên chuyển sang khóa dự án để có các biện pháp bảo mật tốt nhất, mặc dù quyền truy cập qua phương pháp này hiện vẫn được hỗ trợ.

Hãy nhớ rằng khóa API của bạn là một bí mật! Không chia sẻ nó với người khác hoặc hiển thị nó trong bất kỳ mã phía máy khách nào (trình duyệt, ứng dụng). Yêu cầu sản xuất phải được định tuyến qua máy chủ phụ trợ của riêng bạn, nơi khóa API của bạn có thể được tải an toàn từ biến môi trường hoặc dịch vụ quản lý khóa.

Tất cả các yêu cầu API phải bao gồm khóa API của bạn trong tiêu đề HTTP như sau:Authorization

Authorization: Bearer OPENAI_API_KEY

Tổ chức và dự án (tùy chọn)

Đối với người dùng thuộc nhiều tổ chức hoặc đang truy cập dự án của họ thông qua khóa API người dùng cũ, bạn có thể chuyển tiêu đề để chỉ định tổ chức và dự án nào được sử dụng cho yêu cầu API. Mức sử dụng từ các yêu cầu API này sẽ được tính là mức sử dụng cho tổ chức và dự án được chỉ định.

Để truy nhập trong một tổ chức, hãy bỏ qua tiêu đềDefault project``OpenAI-Project

Ví dụ về lệnh curl:

1 2 3 4 curl https://api.openai.com/v1/models \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Organization: org-R5LrxYr03PtejHtgc8MQgFnj" \ -H "OpenAI-Project: $PROJECT_ID"

Ví dụ với gói Python:openai

1 2 3 4 5 6 from openai import OpenAI client = OpenAI( organization='org-R5LrxYr03PtejHtgc8MQgFnj', project='$PROJECT_ID', )

Ví dụ với gói Node.js:openai

1 2 3 4 5 6 import OpenAI from "openai"; const openai = new OpenAI({ organization: "org-R5LrxYr03PtejHtgc8MQgFnj", project: "$PROJECT_ID", });

Bạn có thể tìm thấy ID tổ chức trên trang Thiết đặt tổ chức của mình. ID dự án có thể được tìm thấy trên trang Cài đặt chung của bạn bằng cách chọn dự án cụ thể.

Đưa ra yêu cầu

Bạn có thể dán lệnh bên dưới vào thiết bị đầu cuối để chạy yêu cầu API đầu tiên. Đảm bảo thay thế bằng khóa API bí mật của bạn. Nếu bạn đang sử dụng khóa người dùng cũ và bạn có nhiều dự án, bạn cũng sẽ cần chỉ định ID dự án. Để cải thiện bảo mật, chúng tôi khuyên bạn nên chuyển sang khóa dựa trên dự án.$OPENAI_API_KEY

1 2 3 4 5 6 7 8 curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Say this is a test!"}], "temperature": 0.7 }'

Yêu cầu này truy vấn mô hình (mà dưới mui xe trỏ đến một gpt-4o-minigpt-4o-mini Biến thể mô hình) để hoàn thành văn bản bắt đầu bằng lời nhắc "Nói đây là một bài kiểm tra". Bạn sẽ nhận được phản hồi tương tự như sau:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 { "id": "chatcmpl-abc123", "object": "chat.completion", "created": 1677858242, "model": "gpt-4o-mini", "usage": { "prompt_tokens": 13, "completion_tokens": 7, "total_tokens": 20 }, "choices": [ { "message": { "role": "assistant", "content": "\n\nThis is a test!" }, "logprobs": null, "finish_reason": "stop", "index": 0 } ] }

Bây giờ bạn đã tạo hoàn thành cuộc trò chuyện đầu tiên của mình, hãy chia nhỏ đối tượng phản hồi. Chúng ta có thể thấy is có nghĩa là API đã trả về toàn bộ quá trình hoàn thành trò chuyện do mô hình tạo ra mà không gặp phải bất kỳ giới hạn nào. Trong danh sách lựa chọn, chúng tôi chỉ tạo một thư duy nhất nhưng bạn có thể đặt tham số để tạo nhiều lựa chọn tin nhắn.finish_reason``stop``n

Streaming

API OpenAI cung cấp khả năng truyền phản hồi trở lại máy khách để cho phép kết quả một phần cho các yêu cầu nhất định. Để đạt được điều này, chúng tôi tuân theo tiêu chuẩn Sự kiện do máy chủ gửi. Các thư viện Node và Python chính thức của chúng tôi bao gồm các trình trợ giúp để phân tích cú pháp các sự kiện này đơn giản hơn.

Tính năng phát trực tuyến được hỗ trợ cho cả API Hoàn thành cuộc trò chuyện và API Trợ lý. Phần này tập trung vào cách hoạt động của tính năng phát trực tuyến đối với Hoàn tất cuộc trò chuyện. Tìm hiểu thêm về cách hoạt động của tính năng phát trực tuyến trong API Trợ lý tại đây.

Trong Python, một yêu cầu phát trực tuyến trông giống như:

1 2 3 4 5 6 7 8 9 10 11 12 from openai import OpenAI client = OpenAI() stream = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": "Say this is a test"}], stream=True, ) for chunk in stream: if chunk.choices[0].delta.content is not None: print(chunk.choices[0].delta.content, end="")

Trong Node / Typescript, một yêu cầu phát trực tuyến trông giống như:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 import OpenAI from "openai"; const openai = new OpenAI(); async function main() { const stream = await openai.chat.completions.create({ model: "gpt-4o-mini", messages: [{ role: "user", content: "Say this is a test" }], stream: true, }); for await (const chunk of stream) { process.stdout.write(chunk.choices[0]?.delta?.content || ""); } } main();

Phân tích cú pháp sự kiện do máy chủ gửi

Phân tích cú pháp các sự kiện do Server gửi là không tầm thường và nên được thực hiện một cách thận trọng. Các chiến lược đơn giản như tách theo một dòng mới có thể dẫn đến lỗi phân tích cú pháp. Chúng tôi khuyên bạn nên sử dụng các thư viện máy khách hiện có khi có thể.

Tạo giọng nói

trụ https://api.openai.com/v1/audio/speech

Tạo âm thanh từ văn bản đầu vào.

Nội dung yêu cầu

Văn bản để tạo âm thanh cho. Độ dài tối đa là 4096 ký tự.

Định dạng để âm thanh trong. Các định dạng được hỗ trợ là , , , , , và .mp3``opus``aac``flac``wav``pcm

Tốc độ của âm thanh được tạo ra. Chọn một giá trị từ đến . là mặc định.0.25``4.0``1.0

Trở lại

1 2 3 4 5 6 7 8 9 curl https://api.openai.com/v1/audio/speech \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "tts-1", "input": "The quick brown fox jumped over the lazy dog.", "voice": "alloy" }' \ --output speech.mp3

Tạo bản chép lời

trụ https://api.openai.com/v1/audio/transcriptions

Phiên âm âm thanh sang ngôn ngữ nhập.

Nội dung yêu cầu

Đối tượng tệp âm thanh (không phải tên tệp) để phiên âm, ở một trong các định dạng sau: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav hoặc webm.

ID của mô hình để sử dụng. Chỉ (được cung cấp bởi mô hình Whisper V2 mã nguồn mở của chúng tôi) hiện có sẵn.whisper-1

Ngôn ngữ của âm thanh đầu vào. Cung cấp ngôn ngữ đầu vào ở định dạng ISO-639-1 sẽ cải thiện độ chính xác và độ trễ.

Văn bản tùy chọn để hướng dẫn kiểu của mô hình hoặc tiếp tục phân đoạn âm thanh trước đó. Lời nhắc phải khớp với ngôn ngữ âm thanh.

Định dạng của đầu ra bản chép lời, ở một trong các tùy chọn sau: , , , , hoặc .json``text``srt``verbose_json``vtt

Nhiệt độ lấy mẫu, từ 0 đến 1. Các giá trị cao hơn như 0,8 sẽ làm cho đầu ra ngẫu nhiên hơn, trong khi các giá trị thấp hơn như 0,2 sẽ làm cho nó tập trung và xác định hơn. Nếu được đặt thành 0, mô hình sẽ sử dụng xác suất nhật ký để tự động tăng nhiệt độ cho đến khi đạt đến ngưỡng nhất định.

Dấu thời gian chi tiết để điền cho phiên âm này. phải được đặt để sử dụng độ chi tiết của dấu thời gian. Một hoặc cả hai tùy chọn này được hỗ trợ: , hoặc . Lưu ý: Không có độ trễ bổ sung cho dấu thời gian phân đoạn, nhưng việc tạo dấu thời gian từ sẽ làm tăng thêm độ trễ.response_format``verbose_json``word``segment

Trở lại

1 2 3 4 5 curl https://api.openai.com/v1/audio/transcriptions \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/audio.mp3" \ -F model="whisper-1"

1 2 3 { "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that." }

Tạo bản dịch

trụ https://api.openai.com/v1/audio/translations

Dịch âm thanh sang tiếng Anh.

Nội dung yêu cầu

Đối tượng tệp âm thanh (không phải tên tệp) dịch, ở một trong các định dạng sau: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav hoặc webm.

ID của mô hình để sử dụng. Chỉ (được cung cấp bởi mô hình Whisper V2 mã nguồn mở của chúng tôi) hiện có sẵn.whisper-1

Văn bản tùy chọn để hướng dẫn kiểu của mô hình hoặc tiếp tục phân đoạn âm thanh trước đó. Lời nhắc phải bằng tiếng Anh.

Định dạng của đầu ra bản chép lời, ở một trong các tùy chọn sau: , , , , hoặc .json``text``srt``verbose_json``vtt

Trở lại

1 2 3 4 5 curl https://api.openai.com/v1/audio/translations \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: multipart/form-data" \ -F file="@/path/to/file/german.m4a" \ -F model="whisper-1"

1 2 3 { "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?" }

Đối tượng phiên âm (JSON)

Đại diện cho phản hồi phiên âm được trả về bởi mô hình, dựa trên đầu vào được cung cấp.

1 2 3 { "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that." }

Đối tượng phiên âm (Verbose JSON)

Đại diện cho phản hồi phiên âm json dài dòng được trả về bởi model, dựa trên đầu vào được cung cấp.

Ngôn ngữ của âm thanh đầu vào.

Thời lượng của âm thanh đầu vào.

Các từ được trích xuất và dấu thời gian tương ứng của chúng.

Các phân đoạn của văn bản được phiên âm và các chi tiết tương ứng của chúng.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 { "task": "transcribe", "language": "english", "duration": 8.470000267028809, "text": "The beach was a popular spot on a hot summer day. People were swimming in the ocean, building sandcastles, and playing beach volleyball.", "segments": [ { "id": 0, "seek": 0, "start": 0.0, "end": 3.319999933242798, "text": " The beach was a popular spot on a hot summer day.", "tokens": [ 50364, 440, 7534, 390, 257, 3743, 4008, 322, 257, 2368, 4266, 786, 13, 50530 ], "temperature": 0.0, "avg_logprob": -0.2860786020755768, "compression_ratio": 1.2363636493682861, "no_speech_prob": 0.00985979475080967 }, ... ] }

Tạo hoàn tất cuộc trò chuyện

trụ https://api.openai.com/v1/chat/completions

Tạo phản hồi mẫu cho cuộc trò chuyện đã cho.

Nội dung yêu cầu

Sửa đổi khả năng các mã thông báo được chỉ định xuất hiện trong quá trình hoàn thành.

Chấp nhận một đối tượng JSON ánh xạ mã thông báo (được chỉ định bởi ID mã thông báo của chúng trong trình mã thông báo) thành giá trị thiên vị liên quan từ -100 đến 100. Về mặt toán học, độ lệch được thêm vào nhật ký được tạo bởi mô hình trước khi lấy mẫu. Hiệu ứng chính xác sẽ khác nhau đối với mỗi kiểu máy, nhưng các giá trị từ -1 đến 1 sẽ làm giảm hoặc tăng khả năng lựa chọn; Các giá trị như -100 hoặc 100 sẽ dẫn đến lệnh cấm hoặc lựa chọn độc quyền mã thông báo có liên quan.

Có trả về xác suất nhật ký của mã thông báo đầu ra hay không. Nếu đúng, trả về xác suất nhật ký của mỗi mã thông báo đầu ra được trả về trong of .content``message

Một số nguyên từ 0 đến 20 chỉ định số lượng mã thông báo có khả năng trả về nhất tại mỗi vị trí mã thông báo, mỗi vị trí có xác suất nhật ký liên quan. phải được đặt thành nếu tham số này được sử dụng.logprobs``true

Số lượng mã thông báo tối đa có thể được tạo trong quá trình hoàn thành trò chuyện.

Tổng độ dài của mã thông báo đầu vào và mã thông báo được tạo bị giới hạn bởi độ dài ngữ cảnh của mô hình. Ví dụ về mã Python để đếm mã thông báo.

Có bao nhiêu lựa chọn hoàn thành cuộc trò chuyện để tạo cho mỗi tin nhắn đầu vào. Lưu ý rằng bạn sẽ bị tính phí dựa trên số lượng mã thông báo được tạo trên tất cả các lựa chọn. Giữ như để giảm thiểu chi phí.n``1

An object specifying the format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models newer than .gpt-3.5-turbo-1106

Setting to enables JSON mode, which guarantees the message the model generates is valid JSON.{ "type": "json_object" }

Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if , which indicates the generation exceeded or the conversation exceeded the max context length.finish_reason="length"``max_tokens

This feature is in Beta. If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same and parameters should return the same result. Determinism is not guaranteed, and you should refer to the response parameter to monitor changes in the backend.seed``system_fingerprint

Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service:

If set to 'auto', the system will utilize scale tier credits until they are exhausted.
If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee.

When this parameter is set, the response body will include the utilized.service_tier

Up to 4 sequences where the API will stop generating further tokens.

If set, partial message deltas will be sent, like in ChatGPT. Tokens will be sent as data-only server-sent events as they become available, with the stream terminated by a message. Example Python code.data: [DONE]

Options for streaming response. Only set this when you set .stream: true

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

We generally recommend altering this or but not both.top_p

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

We generally recommend altering this or but not both.temperature

A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.

Controls which (if any) tool is called by the model. means the model will not call any tool and instead generates a message. means the model can pick between generating a message or calling one or more tools. means the model must call one or more tools. Specifying a particular tool via forces the model to call that tool.none``auto``required``{"type": "function", "function": {"name": "my_function"}}

none is the default when no tools are present. is the default if tools are present.auto

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

Deprecated in favor of .tool_choice

Controls which (if any) function is called by the model. means the model will not call a function and instead generates a message. means the model can pick between generating a message or calling a function. Specifying a particular function via forces the model to call that function.none``auto``{"name": "my_function"}

none is the default when no functions are present. is the default if functions are present.auto

Deprecated in favor of .tools

A list of functions the model may generate JSON inputs for.

Returns

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 curl https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "gpt-3.5-turbo", "messages": [ { "role": "system", "content": "You are a helpful assistant." }, { "role": "user", "content": "Hello!" } ] }'

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 { "id": "chatcmpl-123", "object": "chat.completion", "created": 1677652288, "model": "gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices": [{ "index": 0, "message": { "role": "assistant", "content": "\n\nHello there, how may I assist you today?", }, "logprobs": null, "finish_reason": "stop" }], "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 } }

The chat completion object

Represents a chat completion response returned by model, based on the provided input.

A unique identifier for the chat completion.

A list of chat completion choices. Can be more than one if is greater than 1.n

The Unix timestamp (in seconds) of when the chat completion was created.

The model used for the chat completion.

The service tier used for processing the request. This field is only included if the parameter is specified in the request.service_tier

This fingerprint represents the backend configuration that the model runs with.

Can be used in conjunction with the request parameter to understand when backend changes have been made that might impact determinism.seed

The object type, which is always .chat.completion

Usage statistics for the completion request.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 { "id": "chatcmpl-123", "object": "chat.completion", "created": 1677652288, "model": "gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices": [{ "index": 0, "message": { "role": "assistant", "content": "\n\nHello there, how may I assist you today?", }, "logprobs": null, "finish_reason": "stop" }], "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 } }

The chat completion chunk object

Represents a streamed chunk of a chat completion response returned by model, based on the provided input.

A unique identifier for the chat completion. Each chunk has the same ID.

A list of chat completion choices. Can contain more than one elements if is greater than 1. Can also be empty for the last chunk if you set .n``stream_options: {"include_usage": true}

The Unix timestamp (in seconds) of when the chat completion was created. Each chunk has the same timestamp.

The model to generate the completion.

The service tier used for processing the request. This field is only included if the parameter is specified in the request.service_tier

This fingerprint represents the backend configuration that the model runs with. Can be used in conjunction with the request parameter to understand when backend changes have been made that might impact determinism.seed

The object type, which is always .chat.completion.chunk

An optional field that will only be present when you set in your request. When present, it contains a null value except for the last chunk which contains the token usage statistics for the entire request.stream_options: {"include_usage": true}

1 2 3 4 5 6 7 {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"role":"assistant","content":""},"logprobs":null,"finish_reason":null}]} {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{"content":"Hello"},"logprobs":null,"finish_reason":null}]} .... {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1694268190,"model":"gpt-4o-mini", "system_fingerprint": "fp_44709d6fcb", "choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}

Embeddings

Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms.

Related guide: Embeddings

Create embeddings

post https://api.openai.com/v1/embeddings

Creates an embedding vector representing the input text.

Request body

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 ), cannot be an empty string, and any array must be 2048 dimensions or less. Example Python code for counting tokens.text-embedding-ada-002

ID of the model to use. You can use the List models API to see all of your available models, or see our Model overview for descriptions of them.

The format to return the embeddings in. Can be either or floatbase64.

The number of dimensions the resulting output embeddings should have. Only supported in and later models.text-embedding-3

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

Returns

1 2 3 4 5 6 7 8 curl https://api.openai.com/v1/embeddings \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input": "The food was delicious and the waiter...", "model": "text-embedding-ada-002", "encoding_format": "float" }'

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { "object": "list", "data": [ { "object": "embedding", "embedding": [ 0.0023064255, -0.009327292, .... (1536 floats total for ada-002) -0.0028842222, ], "index": 0 } ], "model": "text-embedding-ada-002", "usage": { "prompt_tokens": 8, "total_tokens": 8 } }

The embedding object

Represents an embedding vector returned by embedding endpoint.

The index of the embedding in the list of embeddings.

The embedding vector, which is a list of floats. The length of vector depends on the model as listed in the embedding guide.

The object type, which is always "embedding".

1 2 3 4 5 6 7 8 9 10 { "object": "embedding", "embedding": [ 0.0023064255, -0.009327292, .... (1536 floats total for ada-002) -0.0028842222, ], "index": 0 }

Create fine-tuning job

post https://api.openai.com/v1/fine\_tuning/jobs

Creates a fine-tuning job which begins the process of creating a new model from a given dataset.

Response includes details of the enqueued job including job status and the name of the fine-tuned models once complete.

Learn more about fine-tuning

Request body

The ID of an uploaded file that contains training data.

See upload file for how to upload a file.

Your dataset must be formatted as a JSONL file. Additionally, you must upload your file with the purpose .fine-tune

The contents of the file should differ depending on if the model uses the chat or completions format.

See the fine-tuning guide for more details.

The hyperparameters used for the fine-tuning job.

A string of up to 18 characters that will be added to your fine-tuned model name.

For example, a of "custom-model-name" would produce a model name like .suffix``ft:gpt-3.5-turbo:openai:custom-model-name:7p4lURel

The ID of an uploaded file that contains validation data.

If you provide this file, the data is used to generate validation metrics periodically during fine-tuning. These metrics can be viewed in the fine-tuning results file. The same data should not be present in both train and validation files.

Your dataset must be formatted as a JSONL file. You must upload your file with the purpose .fine-tune

See the fine-tuning guide for more details.

A list of integrations to enable for your fine-tuning job.

The seed controls the reproducibility of the job. Passing in the same seed and job parameters should produce the same results, but may differ in rare cases. If a seed is not specified, one will be generated for you.

Returns

1 2 3 4 5 6 7 curl https://api.openai.com/v1/fine_tuning/jobs \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-BK7bzQj3FfZFXr7DbL6xJwfo", "model": "gpt-3.5-turbo" }'

1 2 3 4 5 6 7 8 9 10 11 12 { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "gpt-3.5-turbo-0125", "created_at": 1614807352, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "status": "queued", "validation_file": null, "training_file": "file-abc123", }

List fine-tuning jobs

get https://api.openai.com/v1/fine\_tuning/jobs

List your organization's fine-tuning jobs

Query parameters

Identifier for the last job from the previous pagination request.

Number of fine-tuning jobs to retrieve.

Returns

1 2 curl https://api.openai.com/v1/fine_tuning/jobs?limit=2 \ -H "Authorization: Bearer $OPENAI_API_KEY"

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { "object": "list", "data": [ { "object": "fine_tuning.job.event", "id": "ft-event-TjX0lMfOniCZX64t9PUQT5hn", "created_at": 1689813489, "level": "warn", "message": "Fine tuning process stopping due to job cancellation", "data": null, "type": "message" }, { ... }, { ... } ], "has_more": true }

List fine-tuning events

get https://api.openai.com/v1/fine\_tuning/jobs/{fine\_tuning\_job\_id}/events

Get status updates for a fine-tuning job.

Path parameters

The ID of the fine-tuning job to get events for.

Query parameters

Identifier for the last event from the previous pagination request.

Number of events to retrieve.

Returns

A list of fine-tuning event objects.

1 2 curl https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/events \ -H "Authorization: Bearer $OPENAI_API_KEY"

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 { "object": "list", "data": [ { "object": "fine_tuning.job.event", "id": "ft-event-ddTJfwuMVpfLXseO0Am0Gqjm", "created_at": 1692407401, "level": "info", "message": "Fine tuning job successfully completed", "data": null, "type": "message" }, { "object": "fine_tuning.job.event", "id": "ft-event-tyiGuB72evQncpH87xe505Sv", "created_at": 1692407400, "level": "info", "message": "New fine-tuned model created: ft:gpt-3.5-turbo:openai::7p4lURel", "data": null, "type": "message" } ], "has_more": true }

List fine-tuning checkpoints

get https://api.openai.com/v1/fine\_tuning/jobs/{fine\_tuning\_job\_id}/checkpoints

List checkpoints for a fine-tuning job.

Path parameters

The ID of the fine-tuning job to get checkpoints for.

Query parameters

Identifier for the last checkpoint ID from the previous pagination request.

Number of checkpoints to retrieve.

Returns

1 2 curl https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/checkpoints \ -H "Authorization: Bearer $OPENAI_API_KEY"

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 { "object": "list" "data": [ { "object": "fine_tuning.job.checkpoint", "id": "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB", "created_at": 1519129973, "fine_tuned_model_checkpoint": "ft:gpt-3.5-turbo-0125:my-org:custom-suffix:96olL566:ckpt-step-2000", "metrics": { "full_valid_loss": 0.134, "full_valid_mean_token_accuracy": 0.874 }, "fine_tuning_job_id": "ftjob-abc123", "step_number": 2000, }, { "object": "fine_tuning.job.checkpoint", "id": "ftckpt_enQCFmOTGj3syEpYVhBRLTSy", "created_at": 1519129833, "fine_tuned_model_checkpoint": "ft:gpt-3.5-turbo-0125:my-org:custom-suffix:7q8mpxmy:ckpt-step-1000", "metrics": { "full_valid_loss": 0.167, "full_valid_mean_token_accuracy": 0.781 }, "fine_tuning_job_id": "ftjob-abc123", "step_number": 1000, }, ], "first_id": "ftckpt_zc4Q7MP6XxulcVzj4MZdwsAB", "last_id": "ftckpt_enQCFmOTGj3syEpYVhBRLTSy", "has_more": true }

Retrieve fine-tuning job

get https://api.openai.com/v1/fine\_tuning/jobs/{fine\_tuning\_job\_id}

Path parameters

The ID of the fine-tuning job.

Returns

1 2 curl https://api.openai.com/v1/fine_tuning/jobs/ft-AF1WoRqd3aJAHsqc9NY7iL8F \ -H "Authorization: Bearer $OPENAI_API_KEY"

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "davinci-002", "created_at": 1692661014, "finished_at": 1692661190, "fine_tuned_model": "ft:davinci-002:my-org:custom_suffix:7q8mpxmy", "organization_id": "org-123", "result_files": [ "file-abc123" ], "status": "succeeded", "validation_file": null, "training_file": "file-abc123", "hyperparameters": { "n_epochs": 4, "batch_size": 1, "learning_rate_multiplier": 1.0 }, "trained_tokens": 5768, "integrations": [], "seed": 0, "estimated_finish": 0 }

Cancel fine-tuning

post https://api.openai.com/v1/fine\_tuning/jobs/{fine\_tuning\_job\_id}/cancel

Immediately cancel a fine-tune job.

Path parameters

The ID of the fine-tuning job to cancel.

Returns

1 2 curl -X POST https://api.openai.com/v1/fine_tuning/jobs/ftjob-abc123/cancel \ -H "Authorization: Bearer $OPENAI_API_KEY"

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "gpt-3.5-turbo-0125", "created_at": 1689376978, "fine_tuned_model": null, "organization_id": "org-123", "result_files": [], "hyperparameters": { "n_epochs": "auto" }, "status": "cancelled", "validation_file": "file-abc123", "training_file": "file-abc123" }

Training format for chat models

The per-line training example of a fine-tuning input file for chat models

A list of tools the model may generate JSON inputs for.

A list of functions the model may generate JSON inputs for.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 { "messages": [ { "role": "user", "content": "What is the weather in San Francisco?" }, { "role": "assistant", "tool_calls": [ { "id": "call_id", "type": "function", "function": { "name": "get_current_weather", "arguments": "{\"location\": \"San Francisco, USA\", \"format\": \"celsius\"}" } } ] } ], "parallel_tool_calls": false, "tools": [ { "type": "function", "function": { "name": "get_current_weather", "description": "Get the current weather", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and country, eg. San Francisco, USA" }, "format": { "type": "string", "enum": ["celsius", "fahrenheit"] } }, "required": ["location", "format"] } } } ] }

Training format for completions models

The per-line training example of a fine-tuning input file for completions models

The input prompt for this training example.

The desired completion for this training example.

1 2 3 4 { "prompt": "What is the answer to 2+2", "completion": "4" }

The fine-tuning job object

The object represents a fine-tuning job that has been created through the API.fine_tuning.job

The object identifier, which can be referenced in the API endpoints.

The Unix timestamp (in seconds) for when the fine-tuning job was created.

For fine-tuning jobs that have , this will contain more information on the cause of the failure.failed

The name of the fine-tuned model that is being created. The value will be null if the fine-tuning job is still running.

The Unix timestamp (in seconds) for when the fine-tuning job was finished. The value will be null if the fine-tuning job is still running.

The hyperparameters used for the fine-tuning job. See the fine-tuning guide for more details.

The base model that is being fine-tuned.

The object type, which is always "fine_tuning.job".

The organization that owns the fine-tuning job.

The compiled results file ID(s) for the fine-tuning job. You can retrieve the results with the Files API.

The current status of the fine-tuning job, which can be either , , , , , or .validating_files``queued``running``succeeded``failed``cancelled

The total number of billable tokens processed by this fine-tuning job. The value will be null if the fine-tuning job is still running.

The file ID used for training. You can retrieve the training data with the Files API.

The file ID used for validation. You can retrieve the validation results with the Files API.

A list of integrations to enable for this fine-tuning job.

The seed used for the fine-tuning job.

The Unix timestamp (in seconds) for when the fine-tuning job is estimated to finish. The value will be null if the fine-tuning job is not running.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 { "object": "fine_tuning.job", "id": "ftjob-abc123", "model": "davinci-002", "created_at": 1692661014, "finished_at": 1692661190, "fine_tuned_model": "ft:davinci-002:my-org:custom_suffix:7q8mpxmy", "organization_id": "org-123", "result_files": [ "file-abc123" ], "status": "succeeded", "validation_file": null, "training_file": "file-abc123", "hyperparameters": { "n_epochs": 4, "batch_size": 1, "learning_rate_multiplier": 1.0 }, "trained_tokens": 5768, "integrations": [], "seed": 0, "estimated_finish": 0 }

The fine-tuning job event object

Fine-tuning job event object

1 2 3 4 5 6 7 { "object": "fine_tuning.job.event", "id": "ftevent-abc123" "created_at": 1677610602, "level": "info", "message": "Created fine-tuning job" }

The fine-tuning job checkpoint object

The object represents a model checkpoint for a fine-tuning job that is ready to use.fine_tuning.job.checkpoint

The checkpoint identifier, which can be referenced in the API endpoints.

The Unix timestamp (in seconds) for when the checkpoint was created.

The name of the fine-tuned checkpoint model that is created.

The step number that the checkpoint was created at.

Metrics at the step number during the fine-tuning job.

The name of the fine-tuning job that this checkpoint was created from.

The object type, which is always "fine_tuning.job.checkpoint".

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { "object": "fine_tuning.job.checkpoint", "id": "ftckpt_qtZ5Gyk4BLq1SfLFWp3RtO3P", "created_at": 1712211699, "fine_tuned_model_checkpoint": "ft:gpt-3.5-turbo-0125:my-org:custom_suffix:9ABel2dg:ckpt-step-88", "fine_tuning_job_id": "ftjob-fpbNQ3H1GrMehXRf8cO97xTN", "metrics": { "step": 88, "train_loss": 0.478, "train_mean_token_accuracy": 0.924, "valid_loss": 10.112, "valid_mean_token_accuracy": 0.145, "full_valid_loss": 0.567, "full_valid_mean_token_accuracy": 0.944 }, "step_number": 88 }

Batch

Create large batches of API requests for asynchronous processing. The Batch API returns completions within 24 hours for a 50% discount.

Related guide: Batch

Create batch

post https://api.openai.com/v1/batches

Creates and executes a batch from an uploaded file of requests

Request body

The ID of an uploaded file that contains requests for the new batch.

See upload file for how to upload a file.

Your input file must be formatted as a JSONL file, and must be uploaded with the purpose . The file can contain up to 50,000 requests, and can be up to 100 MB in size.batch

The endpoint to be used for all requests in the batch. Currently , , and are supported. Note that batches are also restricted to a maximum of 50,000 embedding inputs across all requests in the batch./v1/chat/completions``/v1/embeddings``/v1/completions``/v1/embeddings

The time frame within which the batch should be processed. Currently only is supported.24h

Optional custom metadata for the batch.

Returns

The created Batch object.

1 2 3 4 5 6 7 8 curl https://api.openai.com/v1/batches \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "input_file_id": "file-abc123", "endpoint": "/v1/chat/completions", "completion_window": "24h" }'

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 { "id": "batch_abc123", "object": "batch", "endpoint": "/v1/chat/completions", "errors": null, "input_file_id": "file-abc123", "completion_window": "24h", "status": "validating", "output_file_id": null, "error_file_id": null, "created_at": 1711471533, "in_progress_at": null, "expires_at": null, "finalizing_at": null, "completed_at": null, "failed_at": null, "expired_at": null, "cancelling_at": null, "cancelled_at": null, "request_counts": { "total": 0, "completed": 0, "failed": 0 }, "metadata": { "customer_id": "user_123456789", "batch_description": "Nightly eval job", } }

Retrieve batch

get https://api.openai.com/v1/batches/{batch\_id}

Retrieves a batch.

Path parameters

The ID of the batch to retrieve.

Returns

The Batch object matching the specified ID.

1 2 3 curl https://api.openai.com/v1/batches/batch_abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 { "id": "batch_abc123", "object": "batch", "endpoint": "/v1/completions", "errors": null, "input_file_id": "file-abc123", "completion_window": "24h", "status": "completed", "output_file_id": "file-cvaTdG", "error_file_id": "file-HOWS94", "created_at": 1711471533, "in_progress_at": 1711471538, "expires_at": 1711557933, "finalizing_at": 1711493133, "completed_at": 1711493163, "failed_at": null, "expired_at": null, "cancelling_at": null, "cancelled_at": null, "request_counts": { "total": 100, "completed": 95, "failed": 5 }, "metadata": { "customer_id": "user_123456789", "batch_description": "Nightly eval job", } }

Cancel batch

post https://api.openai.com/v1/batches/{batch\_id}/cancel

Cancels an in-progress batch. The batch will be in status for up to 10 minutes, before changing to , where it will have partial results (if any) available in the output file.cancelling``cancelled

Path parameters

The ID of the batch to cancel.

Returns

The Batch object matching the specified ID.

1 2 3 4 curl https://api.openai.com/v1/batches/batch_abc123/cancel \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -X POST

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 { "id": "batch_abc123", "object": "batch", "endpoint": "/v1/chat/completions", "errors": null, "input_file_id": "file-abc123", "completion_window": "24h", "status": "cancelling", "output_file_id": null, "error_file_id": null, "created_at": 1711471533, "in_progress_at": 1711471538, "expires_at": 1711557933, "finalizing_at": null, "completed_at": null, "failed_at": null, "expired_at": null, "cancelling_at": 1711475133, "cancelled_at": null, "request_counts": { "total": 100, "completed": 23, "failed": 1 }, "metadata": { "customer_id": "user_123456789", "batch_description": "Nightly eval job", } }

List batch

get https://api.openai.com/v1/batches

List your organization's batches.

Query parameters

A cursor for use in pagination. is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.after

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

Returns

A list of paginated Batch objects.

1 2 3 curl https://api.openai.com/v1/batches?limit=2 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json"

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 { "object": "list", "data": [ { "id": "batch_abc123", "object": "batch", "endpoint": "/v1/chat/completions", "errors": null, "input_file_id": "file-abc123", "completion_window": "24h", "status": "completed", "output_file_id": "file-cvaTdG", "error_file_id": "file-HOWS94", "created_at": 1711471533, "in_progress_at": 1711471538, "expires_at": 1711557933, "finalizing_at": 1711493133, "completed_at": 1711493163, "failed_at": null, "expired_at": null, "cancelling_at": null, "cancelled_at": null, "request_counts": { "total": 100, "completed": 95, "failed": 5 }, "metadata": { "customer_id": "user_123456789", "batch_description": "Nightly job", } }, { ... }, ], "first_id": "batch_abc123", "last_id": "batch_abc456", "has_more": true }

The batch object

The object type, which is always .batch

The OpenAI API endpoint used by the batch.

The ID of the input file for the batch.

The time frame within which the batch should be processed.

The current status of the batch.

The ID of the file containing the outputs of successfully executed requests.

The ID of the file containing the outputs of requests with errors.

The Unix timestamp (in seconds) for when the batch was created.

The Unix timestamp (in seconds) for when the batch started processing.

The Unix timestamp (in seconds) for when the batch will expire.

The Unix timestamp (in seconds) for when the batch started finalizing.

The Unix timestamp (in seconds) for when the batch was completed.

The Unix timestamp (in seconds) for when the batch failed.

The Unix timestamp (in seconds) for when the batch expired.

The Unix timestamp (in seconds) for when the batch started cancelling.

The Unix timestamp (in seconds) for when the batch was cancelled.

The request counts for different statuses within the batch.

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maxium of 512 characters long.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 { "id": "batch_abc123", "object": "batch", "endpoint": "/v1/completions", "errors": null, "input_file_id": "file-abc123", "completion_window": "24h", "status": "completed", "output_file_id": "file-cvaTdG", "error_file_id": "file-HOWS94", "created_at": 1711471533, "in_progress_at": 1711471538, "expires_at": 1711557933, "finalizing_at": 1711493133, "completed_at": 1711493163, "failed_at": null, "expired_at": null, "cancelling_at": null, "cancelled_at": null, "request_counts": { "total": 100, "completed": 95, "failed": 5 }, "metadata": { "customer_id": "user_123456789", "batch_description": "Nightly eval job", } }

The request input object

The per-line object of the batch input file

A developer-provided per-request id that will be used to match outputs to inputs. Must be unique for each request in a batch.

The HTTP method to be used for the request. Currently only is supported.POST

The OpenAI API relative URL to be used for the request. Currently , , and are supported./v1/chat/completions``/v1/embeddings``/v1/completions

{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-3.5-turbo", "messages": [{"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is 2+2?"}]}}

The request output object

The per-line object of the batch output and error files

A developer-provided per-request id that will be used to match outputs to inputs.

For requests that failed with a non-HTTP error, this will contain more information on the cause of the failure.

{"id": "batch_req_wnaDys", "custom_id": "request-2", "response": {"status_code": 200, "request_id": "req_c187b3", "body": {"id": "chatcmpl-9758Iw", "object": "chat.completion", "created": 1711475054, "model": "gpt-3.5-turbo", "choices": [{"index": 0, "message": {"role": "assistant", "content": "2 + 2 equals 4."}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 24, "completion_tokens": 15, "total_tokens": 39}, "system_fingerprint": null}}, "error": null}

Upload file

post https://api.openai.com/v1/files

Upload a file that can be used across various endpoints. Individual files can be up to 512 MB, and the size of all files uploaded by one organization can be up to 100 GB.

The Assistants API supports files up to 2 million tokens and of specific file types. See the Assistants Tools guide for details.

The Fine-tuning API only supports files. The input also has certain required formats for fine-tuning chat or completions models..jsonl

The Batch API only supports files up to 100 MB in size. The input also has a specific required format..jsonl

Please contact us if you need to increase these storage limits.

Request body

The File object (not file name) to be uploaded.

The intended purpose of the uploaded file.

Use "assistants" for Assistants and Message files, "vision" for Assistants image file inputs, "batch" for Batch API, and "fine-tune" for Fine-tuning.

Returns

The uploaded File object.

1 2 3 4 curl https://api.openai.com/v1/files \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F purpose="fine-tune" \ -F file="@mydata.jsonl"

1 2 3 4 5 6 7 8 { "id": "file-abc123", "object": "file", "bytes": 120000, "created_at": 1677610602, "filename": "mydata.jsonl", "purpose": "fine-tune", }

List files

get https://api.openai.com/v1/files

Returns a list of files that belong to the user's organization.

Query parameters

Only return files with the given purpose.

Returns

1 2 curl https://api.openai.com/v1/files \ -H "Authorization: Bearer $OPENAI_API_KEY"

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 { "data": [ { "id": "file-abc123", "object": "file", "bytes": 175, "created_at": 1613677385, "filename": "salesOverview.pdf", "purpose": "assistants", }, { "id": "file-abc123", "object": "file", "bytes": 140, "created_at": 1613779121, "filename": "puppy.jsonl", "purpose": "fine-tune", } ], "object": "list" }

Retrieve file

get https://api.openai.com/v1/files/{file\_id}

Returns information about a specific file.

Path parameters

The ID of the file to use for this request.

Returns

The File object matching the specified ID.

1 2 curl https://api.openai.com/v1/files/file-abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY"

1 2 3 4 5 6 7 8 { "id": "file-abc123", "object": "file", "bytes": 120000, "created_at": 1677610602, "filename": "mydata.jsonl", "purpose": "fine-tune", }

Delete file

delete https://api.openai.com/v1/files/{file\_id}

Delete a file.

Path parameters

The ID of the file to use for this request.

Returns

1 2 3 curl https://api.openai.com/v1/files/file-abc123 \ -X DELETE \ -H "Authorization: Bearer $OPENAI_API_KEY"

1 2 3 4 5 { "id": "file-abc123", "object": "file", "deleted": true }

Retrieve file content

get https://api.openai.com/v1/files/{file\_id}/content

Returns the contents of the specified file.

Path parameters

The ID of the file to use for this request.

Returns

1 2 curl https://api.openai.com/v1/files/file-abc123/content \ -H "Authorization: Bearer $OPENAI_API_KEY" > file.jsonl

The file object

The object represents a document that has been uploaded to OpenAI.File

The file identifier, which can be referenced in the API endpoints.

The size of the file, in bytes.

The Unix timestamp (in seconds) for when the file was created.

The object type, which is always .file

The intended purpose of the file. Supported values are , , , , , and .assistants``assistants_output``batch``batch_output``fine-tune``fine-tune-results``vision

Deprecated. The current status of the file, which can be either , , or .uploaded``processed``error

Deprecated. For details on why a fine-tuning training file failed validation, see the field on .error``fine_tuning.job

1 2 3 4 5 6 7 8 { "id": "file-abc123", "object": "file", "bytes": 120000, "created_at": 1677610602, "filename": "salesOverview.pdf", "purpose": "assistants", }

Uploads

Allows you to upload large files in multiple parts.

Create upload

post https://api.openai.com/v1/uploads

Creates an intermediate Upload object that you can add Parts to. Currently, an Upload can accept at most 8 GB in total and expires after an hour after you create it.

Once you complete the Upload, we will create a File object that contains all the parts you uploaded. This File is usable in the rest of our platform as a regular File object.

For certain s, the correct must be specified. Please refer to documentation for the supported MIME types for your use case:purpose``mime_type

Assistants

For guidance on the proper filename extensions for each purpose, please follow the documentation on creating a File.

Request body

The name of the file to upload.

The number of bytes in the file you are uploading.

The MIME type of the file.

This must fall within the supported MIME types for your file purpose. See the supported MIME types for assistants and vision.

Returns

The Upload object with status .pending

1 2 3 4 5 6 7 8 curl https://api.openai.com/v1/uploads \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "purpose": "fine-tune", "filename": "training_examples.jsonl", "bytes": 2147483648, "mime_type": "text/jsonl" }'

1 2 3 4 5 6 7 8 9 10 { "id": "upload_abc123", "object": "upload", "bytes": 2147483648, "created_at": 1719184911, "filename": "training_examples.jsonl", "purpose": "fine-tune", "status": "pending", "expires_at": 1719127296 }

Add upload part

post https://api.openai.com/v1/uploads/{upload\_id}/parts

Adds a Part to an Upload object. A Part represents a chunk of bytes from the file you are trying to upload.

Each Part can be at most 64 MB, and you can add Parts until you hit the Upload maximum of 8 GB.

It is possible to add multiple Parts in parallel. You can decide the intended order of the Parts when you complete the Upload.

Path parameters

Request body

The chunk of bytes for this Part.

Returns

1 2 curl https://api.openai.com/v1/uploads/upload_abc123/parts -F data="aHR0cHM6Ly9hcGkub3BlbmFpLmNvbS92MS91cGxvYWRz..."

1 2 3 4 5 6 { "id": "part_def456", "object": "upload.part", "created_at": 1719185911, "upload_id": "upload_abc123" }

Complete upload

post https://api.openai.com/v1/uploads/{upload\_id}/complete

Completes the Upload.

Within the returned Upload object, there is a nested File object that is ready to use in the rest of the platform.

You can specify the order of the Parts by passing in an ordered list of the Part IDs.

The number of bytes uploaded upon completion must match the number of bytes initially specified when creating the Upload object. No Parts may be added after an Upload is completed.

Path parameters

Request body

The ordered list of Part IDs.

The optional md5 checksum for the file contents to verify if the bytes uploaded matches what you expect.

Returns

The Upload object with status with an additional property containing the created usable File object.completed``file

1 2 3 4 curl https://api.openai.com/v1/uploads/upload_abc123/complete -d '{ "part_ids": ["part_def456", "part_ghi789"] }'

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { "id": "upload_abc123", "object": "upload", "bytes": 2147483648, "created_at": 1719184911, "filename": "training_examples.jsonl", "purpose": "fine-tune", "status": "completed", "expires_at": 1719127296, "file": { "id": "file-xyz321", "object": "file", "bytes": 2147483648, "created_at": 1719186911, "filename": "training_examples.jsonl", "purpose": "fine-tune", } }

Cancel upload

post https://api.openai.com/v1/uploads/{upload\_id}/cancel

Cancels the Upload. No Parts may be added after an Upload is cancelled.

Path parameters

Returns

The Upload object with status .cancelled

curl https://api.openai.com/v1/uploads/upload_abc123/cancel

1 2 3 4 5 6 7 8 9 10 { "id": "upload_abc123", "object": "upload", "bytes": 2147483648, "created_at": 1719184911, "filename": "training_examples.jsonl", "purpose": "fine-tune", "status": "cancelled", "expires_at": 1719127296 }

The upload object

The Upload object can accept byte chunks in the form of Parts.

The Upload unique identifier, which can be referenced in API endpoints.

The Unix timestamp (in seconds) for when the Upload was created.

The name of the file to be uploaded.

The intended number of bytes to be uploaded.

The status of the Upload.

The Unix timestamp (in seconds) for when the Upload was created.

The object type, which is always "upload".

The object represents a document that has been uploaded to OpenAI.File

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { "id": "upload_abc123", "object": "upload", "bytes": 2147483648, "created_at": 1719184911, "filename": "training_examples.jsonl", "purpose": "fine-tune", "status": "completed", "expires_at": 1719127296, "file": { "id": "file-xyz321", "object": "file", "bytes": 2147483648, "created_at": 1719186911, "filename": "training_examples.jsonl", "purpose": "fine-tune", } }

The upload part object

The upload Part represents a chunk of bytes we can add to an Upload object.

The upload Part unique identifier, which can be referenced in API endpoints.

The Unix timestamp (in seconds) for when the Part was created.

The ID of the Upload object that this Part was added to.

The object type, which is always .upload.part

1 2 3 4 5 6 { "id": "part_def456", "object": "upload.part", "created_at": 1719186911, "upload_id": "upload_abc123" }

Images

Given a prompt and/or an input image, the model will generate a new image.

Related guide: Image generation

Create image

post https://api.openai.com/v1/images/generations

Creates an image given a prompt.

Request body

A text description of the desired image(s). The maximum length is 1000 characters for and 4000 characters for .dall-e-2``dall-e-3

The model to use for image generation.

The number of images to generate. Must be between 1 and 10. For , only is supported.dall-e-3``n=1

The quality of the image that will be generated. creates images with finer details and greater consistency across the image. This param is only supported for .hd``dall-e-3

The format in which the generated images are returned. Must be one of or . URLs are only valid for 60 minutes after the image has been generated.url``b64_json

The size of the generated images. Must be one of , , or for . Must be one of , , or for models.256x256``512x512``1024x1024``dall-e-2``1024x1024``1792x1024``1024x1792``dall-e-3

The style of the generated images. Must be one of or . Vivid causes the model to lean towards generating hyper-real and dramatic images. Natural causes the model to produce more natural, less hyper-real looking images. This param is only supported for .vivid``natural``dall-e-3

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

Returns

Returns a list of image objects.

1 2 3 4 5 6 7 8 9 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" }'

1 2 3 4 5 6 7 8 9 10 11 { "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] }

Create image edit

post https://api.openai.com/v1/images/edits

Creates an edited or extended image given an original image and a prompt.

Request body

The image to edit. Must be a valid PNG file, less than 4MB, and square. If mask is not provided, image must have transparency, which will be used as the mask.

A text description of the desired image(s). The maximum length is 1000 characters.

An additional image whose fully transparent areas (e.g. where alpha is zero) indicate where should be edited. Must be a valid PNG file, less than 4MB, and have the same dimensions as .image``image

The model to use for image generation. Only is supported at this time.dall-e-2

The number of images to generate. Must be between 1 and 10.

The size of the generated images. Must be one of , , or .256x256``512x512``1024x1024

The format in which the generated images are returned. Must be one of or . URLs are only valid for 60 minutes after the image has been generated.url``b64_json

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

Returns

Returns a list of image objects.

1 2 3 4 5 6 7 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"

1 2 3 4 5 6 7 8 9 10 11 { "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] }

Create image variation

post https://api.openai.com/v1/images/variations

Creates a variation of a given image.

Request body

The image to use as the basis for the variation(s). Must be a valid PNG file, less than 4MB, and square.

The model to use for image generation. Only is supported at this time.dall-e-2

The number of images to generate. Must be between 1 and 10. For , only is supported.dall-e-3``n=1

The format in which the generated images are returned. Must be one of or . URLs are only valid for 60 minutes after the image has been generated.url``b64_json

The size of the generated images. Must be one of , , or .256x256``512x512``1024x1024

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

Returns

Returns a list of image objects.

1 2 3 4 5 curl https://api.openai.com/v1/images/variations \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -F image="@otter.png" \ -F n=2 \ -F size="1024x1024"

1 2 3 4 5 6 7 8 9 10 11 { "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] }

The image object

Represents the url or the content of an image generated by the OpenAI API.

The base64-encoded JSON of the generated image, if is .response_format``b64_json

The URL of the generated image, if is (default).response_format``url

The prompt that was used to generate the image, if there was any revision to the prompt.

1 2 3 4 { "url": "...", "revised_prompt": "..." }

Models

List and describe the various models available in the API. You can refer to the Models documentation to understand what models are available and the differences between them.

List models

get https://api.openai.com/v1/models

Lists the currently available models, and provides basic information about each one such as the owner and availability.

Returns

1 2 curl https://api.openai.com/v1/models \ -H "Authorization: Bearer $OPENAI_API_KEY"

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 { "object": "list", "data": [ { "id": "model-id-0", "object": "model", "created": 1686935002, "owned_by": "organization-owner" }, { "id": "model-id-1", "object": "model", "created": 1686935002, "owned_by": "organization-owner", }, { "id": "model-id-2", "object": "model", "created": 1686935002, "owned_by": "openai" }, ], "object": "list" }

Retrieve model

get https://api.openai.com/v1/models/{model}

Retrieves a model instance, providing basic information about the model such as the owner and permissioning.

Path parameters

The ID of the model to use for this request

Returns

The model object matching the specified ID.

1 2 curl https://api.openai.com/v1/models/gpt-3.5-turbo-instruct \ -H "Authorization: Bearer $OPENAI_API_KEY"

1 2 3 4 5 6 { "id": "gpt-3.5-turbo-instruct", "object": "model", "created": 1686935002, "owned_by": "openai" }

Delete a fine-tuned model

delete https://api.openai.com/v1/models/{model}

Delete a fine-tuned model. You must have the Owner role in your organization to delete a model.

Path parameters

Returns

1 2 3 curl https://api.openai.com/v1/models/ft:gpt-3.5-turbo:acemeco:suffix:abc123 \ -X DELETE \ -H "Authorization: Bearer $OPENAI_API_KEY"

1 2 3 4 5 { "id": "ft:gpt-3.5-turbo:acemeco:suffix:abc123", "object": "model", "deleted": true }

The model object

Describes an OpenAI model offering that can be used with the API.

The model identifier, which can be referenced in the API endpoints.

The Unix timestamp (in seconds) when the model was created.

The object type, which is always "model".

The organization that owns the model.

1 2 3 4 5 6 { "id": "davinci", "object": "model", "created": 1686935002, "owned_by": "openai" }

Moderations

Given some input text, outputs if the model classifies it as potentially harmful across several categories.

Related guide: Moderations

Create moderation

post https://api.openai.com/v1/moderations

Classifies if text is potentially harmful.

Request body

The input text to classify

Two content moderations models are available: and .text-moderation-stable``text-moderation-latest

The default is which will be automatically upgraded over time. This ensures you are always using our most accurate model. If you use , we will provide advanced notice before updating the model. Accuracy of may be slightly lower than for .text-moderation-latest``text-moderation-stable``text-moderation-stable``text-moderation-latest

Returns

1 2 3 4 5 6 curl https://api.openai.com/v1/moderations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "input": "I want to kill them." }'

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 { "id": "modr-XXXXX", "model": "text-moderation-005", "results": [ { "flagged": true, "categories": { "sexual": false, "hate": false, "harassment": false, "self-harm": false, "sexual/minors": false, "hate/threatening": false, "violence/graphic": false, "self-harm/intent": false, "self-harm/instructions": false, "harassment/threatening": true, "violence": true, }, "category_scores": { "sexual": 1.2282071e-06, "hate": 0.010696256, "harassment": 0.29842457, "self-harm": 1.5236925e-08, "sexual/minors": 5.7246268e-08, "hate/threatening": 0.0060676364, "violence/graphic": 4.435014e-06, "self-harm/intent": 8.098441e-10, "self-harm/instructions": 2.8498655e-11, "harassment/threatening": 0.63055265, "violence": 0.99011886, } } ] }

The moderation object

Represents if a given text input is potentially harmful.

The unique identifier for the moderation request.

The model used to generate the moderation results.

A list of moderation objects.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 { "id": "modr-XXXXX", "model": "text-moderation-005", "results": [ { "flagged": true, "categories": { "sexual": false, "hate": false, "harassment": false, "self-harm": false, "sexual/minors": false, "hate/threatening": false, "violence/graphic": false, "self-harm/intent": false, "self-harm/instructions": false, "harassment/threatening": true, "violence": true, }, "category_scores": { "sexual": 1.2282071e-06, "hate": 0.010696256, "harassment": 0.29842457, "self-harm": 1.5236925e-08, "sexual/minors": 5.7246268e-08, "hate/threatening": 0.0060676364, "violence/graphic": 4.435014e-06, "self-harm/intent": 8.098441e-10, "self-harm/instructions": 2.8498655e-11, "harassment/threatening": 0.63055265, "violence": 0.99011886, } } ] }

post https://api.openai.com/v1/assistants

Create an assistant with a model and instructions.

Request body

ID of the model to use. You can use the List models API to see all of your available models, or see our Model overview for descriptions of them.

The name of the assistant. The maximum length is 256 characters.

The description of the assistant. The maximum length is 512 characters.

The system instructions that the assistant uses. The maximum length is 256,000 characters.

A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types , , or .code_interpreter``file_search``function

A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the tool requires a list of file IDs, while the tool requires a list of vector store IDs.code_interpreter``file_search

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

We generally recommend altering this or temperature but not both.

Specifies the format that the model must output. Compatible with GPT-4o, GPT-4 Turbo, and all GPT-3.5 Turbo models since .gpt-3.5-turbo-1106

Setting to enables JSON mode, which guarantees the message the model generates is valid JSON.{ "type": "json_object" }

Returns

1 2 3 4 5 6 7 8 9 10 curl "https://api.openai.com/v1/assistants" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" \ -d '{ "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", "name": "Math Tutor", "tools": [{"type": "code_interpreter"}], "model": "gpt-4-turbo" }'

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { "id": "asst_abc123", "object": "assistant", "created_at": 1698984975, "name": "Math Tutor", "description": null, "model": "gpt-4-turbo", "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", "tools": [ { "type": "code_interpreter" } ], "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" }

get https://api.openai.com/v1/assistants

Returns a list of assistants.

Query parameters

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.

Sort order by the timestamp of the objects. for ascending order and for descending order.created_at``asc``desc

A cursor for use in pagination. is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.before

Returns

1 2 3 4 curl "https://api.openai.com/v1/assistants?order=desc&limit=20" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2"

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 { "object": "list", "data": [ { "id": "asst_abc123", "object": "assistant", "created_at": 1698982736, "name": "Coding Tutor", "description": null, "model": "gpt-4-turbo", "instructions": "You are a helpful assistant designed to make me better at coding!", "tools": [], "tool_resources": {}, "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" }, { "id": "asst_abc456", "object": "assistant", "created_at": 1698982718, "name": "My Assistant", "description": null, "model": "gpt-4-turbo", "instructions": "You are a helpful assistant designed to make me better at coding!", "tools": [], "tool_resources": {}, "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" }, { "id": "asst_abc789", "object": "assistant", "created_at": 1698982643, "name": null, "description": null, "model": "gpt-4-turbo", "instructions": null, "tools": [], "tool_resources": {}, "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" } ], "first_id": "asst_abc123", "last_id": "asst_abc789", "has_more": false }

get https://api.openai.com/v1/assistants/{assistant\_id}

Retrieves an assistant.

Path parameters

The ID of the assistant to retrieve.

Returns

The assistant object matching the specified ID.

1 2 3 4 curl https://api.openai.com/v1/assistants/asst_abc123 \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2"

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { "id": "asst_abc123", "object": "assistant", "created_at": 1699009709, "name": "HR Helper", "description": null, "model": "gpt-4-turbo", "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", "tools": [ { "type": "file_search" } ], "metadata": {}, "top_p": 1.0, "temperature": 1.0, "response_format": "auto" }

post https://api.openai.com/v1/assistants/{assistant\_id}

Modifies an assistant.

Path parameters

The ID of the assistant to modify.