OpenAI-API interface document (Chinese version)

OpenAI-API-Chinese version

1. Introduction _

If you want to use our API, you can interact with the API from any language via HTTP requests , or use our official Python bindings, official Node.js library , or a community-maintained library .

To install the official Python bindings, run the following command:

python

copy code

pip install openai

To install the official Node.js library , run the following command in your Node.js project directory:

copy code

npm install openai

2. Authentication _

1. OpenAI-API-KEY

OpenAI APIs use API keys for authentication. Please visit your API key page to retrieve the API key you used in your request.

Remember, your API key is confidential! Do not share it with others or expose it in any client-side code (browser, application). Production requests must be routed through your own backend server, where your API keys can be securely loaded from environment variables or key management services.

All API requests should Authorization include your API key in an HTTP header like so:

http

copy code

# 注意Bearer OPENAI_API_KEY，Bearer的后面是有一个空格的 Authorization: Bearer OPENAI_API_KEY

2. OpenAI-Organization

Requesting organization Requesting organization

For users belonging to multiple organizations, you can pass a header specifying which organizations to use for API requests. Usage of these API requests will count against the subscription quota for the specified organization.

Example curl command:

http

copy code

curl https://api.openai.com/v1/models \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Organization: org-gth0C8mT2wnKealyCkSRrpQk"

Example using the openai Python package :

python

copy code

import os import openai openai.organization = "org-gth0C8mT2wnKealyCkSRrpQk" openai.api_key = os.getenv("OPENAI_API_KEY") openai.Model.list()

Example using the openai Node.js package :

copy code

import { Configuration, OpenAIApi } from "openai"; const configuration = new Configuration({ organization: "org-gth0C8mT2wnKealyCkSRrpQk", apiKey: process.env.OPENAI_API_KEY, }); const openai = new OpenAIApi(configuration); const response = await openai.listEngines();

The Organization ID can be found on the Organization Settings page

Three. Making requests

You can paste the command below into your terminal to run your first API request. Make sure to replace $OPENAI_API_KEY with your API key .

http

copy code

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": "user", "content": "Say this is a test!"}], "temperature": 0.7 }'

This request queries gpt-3.5-turbo模型to complete the text starting with the prompt "Say this is a test". You should receive a response similar to:

json

copy code

{ "id":"chatcmpl-abc123", "object":"chat.completion", "created":1677858242, "model":"gpt-3.5-turbo-0301", "usage":{ "prompt_tokens":13, "completion_tokens":7, "total_tokens":20 }, "choices":[ { "message":{ "role":"assistant", "content":"\n\nThis is a test!" }, "finish_reason":"stop", "index":0 } ] }

You have now generated your first chat completion. We can see finish_reason yes stop, which means the API returned a complete completion of the model generation. In the above request, we only generated one message, but you can set n the parameter to generate multiple messages option. In this example, gpt-3.5-turbo is used for a more traditional text completion task . The model is also optimized for chat applications .

Four. Models model

Lists and describes the various models available in the API. You can refer to the model documentation to learn about the available models and the differences between them.

1. List models list models

http

copy code

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

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

Request a demo:

http

copy code

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

response:

json

copy code

{ "data": [ { "id": "model-id-0", "object": "model", "owned_by": "organization-owner", "permission": [...] }, { "id": "model-id-1", "object": "model", "owned_by": "organization-owner", "permission": [...] }, { "id": "model-id-2", "object": "model", "owned_by": "openai", "permission": [...] }, ], "object": "list" }

2. Retrieve model retrieval model

http

copy code

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

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

where, model is a required string type , the ID of the model used for this request .

Request a demo:

http

copy code

curl https://api.openai.com/v1/models/text-davinci-003 \ -H "Authorization: Bearer $OPENAI_API_KEY"

response:

json

copy code

{ "id": "text-davinci-003", "object": "model", "owned_by": "openai", "permission": [...] }

Five. Completions completed

Given a hint, the model will return one or more predicted completions, and may also return the probability of an alternative token at each position.

1. Create completion

http

copy code

POST https://api.openai.com/v1/completions

Created for the provided prompt and arguments.

Request a demo:

http

copy code

curl https://api.openai.com/v1/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "text-davinci-003", "prompt": "Say this is a test", "max_tokens": 7, "temperature": 0 }'

response:

json

copy code

{ "id": "cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7", "object": "text_completion", "created": 1589478378, "model": "text-davinci-003", "choices": [ { "text": "\n\nThis is indeed a test", "index": 0, "logprobs": null, "finish_reason": "length" } ], "usage": { "prompt_tokens": 5, "completion_tokens": 7, "total_tokens": 12 } }

Request body (detailed explanation of input parameters)

model (string, required)

The ID of the model to use. You can use the List Models API (GET api.openai.com/v1/models ) to view all available models, or see Models Overview for their descriptions.

prompt （string or array，选填，Defaults to <|endoftext|>）

Hints for generating completions, encoded as strings, arrays of strings, arrays of tokens, or arrays of arrays of tokens.

Note that |endoftext| is the document separator that the model sees during training, so if no hint is specified, the model will generate as if from the beginning of a new document.

suffix （string，选填，Defaults to null）

The suffix after the inserted text is done.

max_tokens （integer，选填，Defaults to 16）

The maximum number of tokens to generate upon completion .

A hint max_tokens 's token count cannot exceed the model's context length. Most models have a context length of 2048 tokens (except the latest model, which supports 4096)

temperature (number, optional, Defaults to 1)

Which 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 usually recommend modifying this ( temperature ) to top_p but both cannot exist at the same time, choose one of the two.

top_p (number, optional, Defaults to 1)

An alternative to temperature sampling is called core sampling, where the model takes into account labeled results with top_p probability quality. Thus, 0.1 means that only markers with the top 10% probability mass are considered.

We generally recommend modifying this ( top_p ) or temperature, but not both.

n （integer，选填，Defaults to 1）

prompt The number of completions for each build.

Note: Since this parameter generates many completions, it can quickly consume your token quota. Use with care, and make sure to set the max_tokens and stop s reasonably.

stream （boolean，选填，Defaults to false）

Whether to return a partial progress stream. If set, tokens will be sent as data server push events as they become available, and streams data: [DONE] are terminated via messages.

logprobs （integer，选填，Defaults to null）

In logprobs the returned list of most likely markers, include the selected marker and the corresponding log-probability.

For example, if logprobs it is 5, the API will return a list of the 5 most likely tags. The API always returns the log probability of the sampled marker, so there may be as many as logprobs+1 elements in the response.

logprobs The maximum value is 5. If you need more, please contact us via our help center and describe your use case.

echo （boolean，选填，Defaults to false）

Echo the prompt in addition to completion

stop （string or array，选填，Defaults to null）

Generate up to 4 sequences, the API will stop generating more tokens. The returned text does not contain stop sequences.

presence_penalty (number, optional, Defaults to 0)

A number between -2.0 and 2.0 . Positive values penalize new tokens based on whether they have appeared in the text so far, increasing the likelihood that the model talks about new topics.

See more about frequency and state penalties

frequency_penalty (number, optional, Defaults to 0)

A number between -2.0 and 2.0. A positive value penalizes new tokens based on their existing frequency in the text, reducing the likelihood that the model will repeat the same row.

See more about frequency and presence penalties

best_of （integer，选填，Defaults to 1）

Generation is done server-side best_of , and the "best" (the one with the highest log probability for each token) is returned. Results cannot be streamed.

When n used with , best_of controls the number of candidate completions, n specifying how many to return - best_of must be greater than n.

Note: Since this parameter generates many completions, it may quickly consume your token quota. Use with care and make sure max_tokens and stop are set appropriately.

logit_bias （map，选填，Defaults to null）

Modifies the likelihood of the specified token appearing on completion.

Accepts a JSON object mapping tokens (specified by token IDs in the GPT tokenizer) to relative bias values from -100 to 100. You can use this tokenizer tool (for GPT-2 and GPT-3) to convert text into token IDs. Mathematically, bias is added to the logits generated by the model before sampling. The exact effect varies by model, but values between -1 and 1 should reduce or increase the likelihood of selection; values like -100 or 100 should cause the associated token to be banned or exclusively selected.

For example, you can pass {"50256": -100} to prevent generating

user (string, optional)

A unique identifier, representing your end user, that helps OpenAI monitor and detect abuse. Learn more .

6. Chat _

Given a list of messages describing a conversation, the model will return a reply.

1. Create chat completion

http

copy code

POST https://api.openai.com/v1/chat/completions

Create a model response for a given chat dialog.

Request a demo:

http

copy code

response:

json

copy code

{ "id": "chatcmpl-123", "object": "chat.completion", "created": 1677652288, "choices": [{ "index": 0, "message": { "role": "assistant", "content": "\n\nHello there, how may I assist you today?", }, "finish_reason": "stop" }], "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 } }

Request body (detailed explanation of input parameters)

model (string, required)

The model ID to use. For details on which models are available for the Chat API, please review the Model Endpoint Compatibility Table

messages (array, required)

List of messages describing the conversation so far

role (string, required)

The author role of this message. system , user or assistant one of

content (string, required)

content of the message

name (string, optional)

The name of the author of this message. Can contain az, AZ, 0-9 and underscore, maximum length is 64 characters

temperature (number, optional, Defaults to 1)

Which 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 usually recommend modifying this ( temperature ) to top_p but both cannot exist at the same time, choose one of the two.

top_p (number, optional, Defaults to 1)

An alternative to temperature sampling is called core sampling, where the model takes into account labeled results with top_p probability quality. Thus, 0.1 means that only markers with the top 10% probability mass are considered.

We generally recommend modifying this ( top_p ) or temperature, but not both.

n （integer，选填，Defaults to 1）

How many chat completion options to generate per input message

stream （boolean，选填，Defaults to false）

If set, partial message deltas will be sent, just like in ChatGPT. Tokens will be sent as data server push events as they become available and streams data: [DONE] are terminated via messages. See the OpenAI Cookbook for example code .

stop （string or array，选填，Defaults to null）

Generate up to 4 sequences, the API will stop generating more tokens.

max_tokens （integer，选填，Defaults to inf）

Maximum number of tokens to generate on chat completion .

The total length of input tokens and generated tokens is limited by the model context length.

presence_penalty (number, optional, Defaults to 0)

A number between -2.0 and 2.0 . Positive values penalize new tokens based on whether they have appeared in the text so far, increasing the likelihood that the model talks about new topics.

See more about frequency and state penalties

frequency_penalty (number, optional, Defaults to 0)

A number between -2.0 and 2.0. A positive value penalizes new tokens based on their existing frequency in the text, reducing the likelihood that the model will repeat the same row.

See more about frequency and presence penalties

logit_bias （map，选填，Defaults to null）

Specifies the likelihood that the marker will appear when modifications are complete.

Accepts a JSON object mapping tokens (specified by token IDs in the tokenizer) to relative bias values from -100 to 100. This bias is added to the logits generated by the model before sampling. The exact effect varies by model, but values between -1 and 1 should reduce or increase selection probability; values like -100 or 100 should result in the associated marker being suppressed or exclusively selected.

user (string, optional)

A unique identifier, representing your end user, that helps OpenAI monitor and detect abuse. Learn more .

Seven . EditsEdit

Given a hint and an instruction, the model returns an edited version of the hint.

1. Create edit

http

copy code

POST https://api.openai.com/v1/edits

Create a new editor for the provided inputs, directives and arguments.

Request a demo:

http

copy code

curl https://api.openai.com/v1/edits \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "model": "text-davinci-edit-001", "input": "What day of the wek is it?", "instruction": "Fix the spelling mistakes" }'

response:

json

copy code

{ "object": "edit", "created": 1589478378, "choices": [ { "text": "What day of the week is it?", "index": 0, } ], "usage": { "prompt_tokens": 25, "completion_tokens": 32, "total_tokens": 57 } }

Request body (detailed explanation of input parameters)

model (string, required)

The model ID to use. text-davinci-edit-001 You can use or model in this endpoint code-davinci-edit-001 .

input (string, optional, Defaults to '')

The input text to use as the starting point for editing.

instruction (string, required)

A description that instructs the model how to edit the prompt.

n （integer，选填，Defaults to 1）

How many edits need to be generated for input and directives.

temperature (number, optional, Defaults to 1)

Which 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 usually recommend modifying this ( temperature ) to top_p but both cannot exist at the same time, choose one of the two.

top_p (number, optional, Defaults to 1)

An alternative to temperature sampling is called core sampling, where the model takes into account labeled results with top_p probability quality. Thus, 0.1 means that only markers with the top 10% probability mass are considered.

We generally recommend modifying this ( top_p ) or temperature, but not both.

Eight . Images

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

Related guide: Image generation .

1. Create image

http

copy code

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

Follow the prompts to create an image.

Request a demo:

http

copy code

curl https://api.openai.com/v1/images/generations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "prompt": "A cute baby sea otter", "n": 2, "size": "1024x1024" }'

response:

json

copy code

{ "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] }

Request body (detailed explanation of input parameters)

prompt (string, required)

A textual description of the desired image. The maximum length is 1000 characters.

n （integer，选填，Defaults to 1）

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

size (string, optional, Defaults to 1024x1024)

The dimensions of the resulting image. Must be one of 256x256 , 512x512 or 1024x1024 .

response_format （string，选填，Defaults to url）

The resulting image return format. Must be one of url or b64_json .

user (string, optional)

A unique identifier, representing your end user, that helps OpenAI monitor and detect abuse. Learn more .

2. Create image edit

http

copy code

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

Create edited or expanded images from original images and cues.

Request a demo:

http

copy code

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"

response:

json

copy code

{ "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] }

Request body (detailed explanation of input parameters)

image (string, required)

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

mask (string, optional)

An extra image whose fully transparent areas (such as those with an alpha value of zero) indicate where the image should be edited. image Must be a valid PNG file, less than 4MB, and the image same dimensions as .

prompt (string, required)

A textual description of the desired image. The maximum length is 1000 characters.

n （integer，选填，Defaults to 1）

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

size (string, optional, Defaults to 1024x1024)

The dimensions of the resulting image. Must be one of 256x256 , 512x512 or 1024x1024 .

response_format （string，选填，Defaults to url）

The resulting image return format. Must be one of url or b64_json .

user (string, optional)

A unique identifier, representing your end user, that helps OpenAI monitor and detect abuse. Learn more .

3. Create image variation

http

copy code

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

Create a variant of the given image.

Request a demo:

http

copy code

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

response:

json

copy code

{ "created": 1589478378, "data": [ { "url": "https://..." }, { "url": "https://..." } ] }

Request body (detailed explanation of input parameters)

image (string, required)

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

n （integer，选填，Defaults to 1）

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

size (string, optional, Defaults to 1024x1024)

The dimensions of the resulting image. Must be one of 256x256 , 512x512 or 1024x1024 .

response_format （string，选填，Defaults to url）

The resulting image return format. Must be one of url or b64_json .

user (string, optional)

A unique identifier, representing your end user, that helps OpenAI monitor and detect abuse. Learn more .

Nine. Embeddings embedded

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

Related guide: Embedding

1. Create embeddings

http

copy code

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

Create an embedding vector representing the input text.

Request a demo:

http

copy code

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" }'

response:

json

copy code

{ "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 } }

Request body (detailed explanation of input parameters)

model (string, required)

The model ID to use . You can see all available models using the List Models API, or see our models overview for their descriptions.

input (string or array, required)

Input text to get an embedding, encoded as a string or an array of tokens. To get embeddings for multiple inputs in a single request, pass an array of string arrays or arrays of token arrays. Each input must be no longer than 8192 tokens in length .

user (string, optional)

A unique identifier, representing your end user, that helps OpenAI monitor and detect abuse. Learn more .

10. Audio _

Learn how to convert audio to text.

Related guide: Speech-to-text

1. Create transcription

http

copy code

POST https://api.openai.com/v1/audio/transcriptions

Transcribe audio into the input language.

Request a demo:

http

copy code

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"

response:

json

copy code

{ "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." }

Request body (detailed explanation of input parameters)

file (string, required)

The audio file to transcribe, in one of the following formats: mp3, mp4, mpeg, mpga, m4a, wav, or webm.

model (string, required)

The model ID to use. Currently only whisper-1 available.

prompt (string, optional)

An optional text to guide the style of the model or to continue the previous audio clip. prompt should match the audio language.

response_format （string，选填，Defaults to json）

Format of transcription output, options include: json, text, srt, verbose_json or vtt.

temperature (number, optional, Defaults to 0)

The sampling temperature is between 0 and 1. Higher values (like 0.8) will make the output more random, while lower values (like 0.2) will make it more focused and deterministic. If set to 0, the model will use the log probability to automatically increase the temperature until certain thresholds are reached.

language (string, optional)

The language of the input audio. Providing the input language in ISO-639-1 format will improve accuracy and latency.

2. Create translation

http

copy code

POST https://api.openai.com/v1/audio/translations

Translate audio into English.

Request a demo:

http

copy code

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"

response:

json

copy code

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

Request body (detailed explanation of input parameters)

file (string, required)

Audio files to be translated must be in one of the following formats: mp3, mp4, mpeg, mpga, m4a, wav or webm.

model (string, required)

The model ID to use. Currently only whisper-1 available.

prompt (string, optional)

An optional text to guide the style of the model or to continue the previous audio clip. prompt should match the audio language.

response_format （string，选填，Defaults to json）

Format of transcription output, options include: json, text, srt, verbose_json or vtt.

temperature (number, optional, Defaults to 0)

The sampling temperature is between 0 and 1. Higher values (like 0.8) will make the output more random, while lower values (like 0.2) will make it more focused and deterministic. If set to 0, the model will use the log probability to automatically increase the temperature until certain thresholds are reached.

11. Files _

Files is used to upload documents and can be used with functions such as Fine-tuning .

1. List files

http

copy code

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

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

Request a demo:

http

copy code

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

response:

json

copy code

{ "data": [ { "id": "file-ccdDZrC3iZVNiQVeEA6Z66wf", "object": "file", "bytes": 175, "created_at": 1613677385, "filename": "train.jsonl", "purpose": "search" }, { "id": "file-XjGxS3KTG0uNmNOK362iJua3", "object": "file", "bytes": 140, "created_at": 1613779121, "filename": "puppy.jsonl", "purpose": "search" } ], "object": "list" }

2. Upload file

http

copy code

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

Upload a file containing documentation to use across endpoints/functions. Currently, all files uploaded by an organization can be up to 1 GB in size. Please contact us if you need to increase your storage limit.

Request a demo:

http

copy code

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

response:

json

copy code

{ "id": "file-XjGxS3KTG0uNmNOK362iJua3", "object": "file", "bytes": 140, "created_at": 1613779121, "filename": "mydata.jsonl", "purpose": "fine-tune" }

Request body (detailed explanation of input parameters)

file (string, required)

The JSON Lines filename to upload .

If purpose set to "fine-tune" , each line is a JSON record with "prompt" and "completion" fields representing your training examples .

purpose (string, required)

The intended use of the uploaded document.

Use "fine-tune" for Fine-tuning . This validates the format of the uploaded file.

3. Delete file

http

copy code

DELETE https://api.openai.com/v1/files/{file_id}

Delete Files.

Request a demo:

http

copy code

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

Among them, {file_id} it is a required item of string type, and the ID of the file used for this request

response:

json

copy code

{ "id": "file-XjGxS3KTG0uNmNOK362iJua3", "object": "file", "deleted": true }

4. Retrieve file

http

copy code

GET https://api.openai.com/v1/files/{file_id}

Return information about a specific file.

Request a demo:

http

copy code

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

Among them, {file_id} it is a required item of string type, and the ID of the file used for this request

response:

json

copy code

{ "id": "file-XjGxS3KTG0uNmNOK362iJua3", "object": "file", "bytes": 140, "created_at": 1613779657, "filename": "mydata.jsonl", "purpose": "fine-tune" }

5. Retrieve file content

http

copy code

GET https://api.openai.com/v1/files/{file_id}/content

Returns the contents of the specified file.

Request a demo:

http

copy code

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

Among them, {file_id} it is a required item of string type, and the ID of the file used for this request

12. Fine- tunes

Manage fine-tuning jobs to tailor the model to your specific training data.

Related guide: Fine-tune models

1. Create fine-tune

http

copy code

POST https://api.openai.com/v1/fine-tunes

Create a job that fine-tunes the specified model from the given dataset.

The response includes details of the job that was enqueued, including the job status and the name of the fine-tuned model upon completion.

Learn more about fine-tuning .

Request a demo:

http

copy code

curl https://api.openai.com/v1/fine-tunes \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d '{ "training_file": "file-XGinujblHPwGLSztz8cPS8XY" }'

response:

json

copy code

Request body (detailed explanation of input parameters)

training_file (string, required)

The ID of the uploaded file containing the training data .

See upload file to learn how to upload a file.

Your dataset must be formatted as a JSONL file , where each training example is a JSON object with "prompt" and "completion" keys. Also, you must upload fine-tune a document with a purpose.

See the fine-tuning guide for more details .

validation_file (string, optional)

The ID of the uploaded file that contains the authentication data .

If you provide this file, the data will be used periodically during fine-tuning to generate validation metrics. These metrics can be viewed in the fine-tuning results file . Your training and validation data should be mutually exclusive.

Your dataset must be formatted as a JSONL file , where each validation example is a JSON object with "prompt" and "completion" keys. Also, you must upload fine-tune a document with a purpose.

See the fine-tuning guide for more details .

model （string，选填，Defaults to curie）

The base model name to fine tune.

You can choose one of these: "ada", "babbage", "curie", "davinci", or a fine-tuned model created after April 21, 2022. To learn more about these models, see the Models documentation.

n_epochs （integer，选填，Defaults to 4）

The number of epochs to train the model. An epoch refers to a complete traversal of the training data set

batch_size （integer，选填，Defaults to null）

The batch size used for training. The batch size is the number of training examples used to train a single forward and backward pass.

By default, the batch size will be dynamically configured to be about 0.2% of the number of training set examples, capped at 256.

In general, we have found that larger batch sizes work better for larger datasets.

learning_rate_multiplier （number，选填，Defaults to null）

The learning rate multiplier used for training. The fine-tuning learning rate is obtained by multiplying the original learning rate used in pre-training by this value.

By default, the multiplier for the learning rate is 0.05, 0.1, or 0.2, depending on the end batch_size(larger batch sizes generally work better with larger learning rates). We recommend trying to experiment with different values in the range 0.02 to 0.2 to find the one that produces the best results.

prompt_loss_weight (number, optional, Defaults to 0.01)

The weight used to hint the loss of tokens. This controls how much the model tries to learn to generate hints (compared to always having completion with a weight of 1.0), and can add a stabilizing effect to training when completions are short.

If the cues are very long (relative to completion), it might make sense to reduce this weight to avoid over-prioritizing learning the cues.

compute_classification_metrics （boolean，选填，Defaults to false）

If set, we use the validation set at the end of each epoch to compute classification-specific metrics such as accuracy and F-1 score. These metrics can be viewed in the results file .

In order to calculate a categorical metric, you must provide one validation_file(验证文件). Also, you must specify for multiclass classification classification_n_classesand for binary classification classification_positive_class.

classification_n_classes （integer，选填，Defaults to null）

The number of categories in the classification task.

This parameter is required in multi-classification tasks.

classification_positive_class （string，选填，Defaults to null）

Positive class in binary classification.

This parameter is required to generate precision, recall and F1 metrics when doing binary classification.

classification_betas （array，选填，Defaults to null）

If this parameter is provided, we will calculate the F-beta score at the specified beta value. The F-beta score is a generalization of the F-1 score. This is only for binary classification.

When beta is 1 (i.e. F-1 score), precision and recall are given equal weight. Larger beta values place more emphasis on recall than precision. Smaller beta values place more emphasis on precision than recall.

suffix （string，选填，Defaults to null）

A string of up to 40 characters in length that will be appended to your fine-tuned model name.

For example, suffix "custom-model-name" would generate a model name such as ada:ft-your-org:custom-model-name-2022-02-15-04-21-04.

2. List fine-tunes

http

copy code

GET https://api.openai.com/v1/fine-tunes

List the organization's fine-tuning jobs

Request a demo:

http

copy code

curl https://api.openai.com/v1/fine-tunes \ -H "Authorization: Bearer $OPENAI_API_KEY"

response:

json

copy code

{ "object": "list", "data": [ { "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F", "object": "fine-tune", "model": "curie", "created_at": 1614807352, "fine_tuned_model": null, "hyperparams": { ... }, "organization_id": "org-...", "result_files": [], "status": "pending", "validation_files": [], "training_files": [ { ... } ], "updated_at": 1614807352, }, { ... }, { ... } ] }

3. Retrieve fine-tune.

http

copy code

GET https://api.openai.com/v1/fine-tunes/{fine_tune_id}

Get information about fine-tuning jobs.

Learn more about fine-tuning .

Request a demo:

http

copy code

curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F \ -H "Authorization: Bearer $OPENAI_API_KEY"

Among them, fine_tune_id it is a character string of type string, which must be passed ; the ID of the fine-tuning job

response:

json

copy code

{ "id": "ft-AF1WoRqd3aJAHsqc9NY7iL8F", "object": "fine-tune", "model": "curie", "created_at": 1614807352, "events": [ { "object": "fine-tune-event", "created_at": 1614807352, "level": "info", "message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0." }, { "object": "fine-tune-event", "created_at": 1614807356, "level": "info", "message": "Job started." }, { "object": "fine-tune-event", "created_at": 1614807861, "level": "info", "message": "Uploaded snapshot: curie:ft-acmeco-2021-03-03-21-44-20." }, { "object": "fine-tune-event", "created_at": 1614807864, "level": "info", "message": "Uploaded result files: file-QQm6ZpqdNwAaVC3aSz5sWwLT." }, { "object": "fine-tune-event", "created_at": 1614807864, "level": "info", "message": "Job succeeded." } ], "fine_tuned_model": "curie:ft-acmeco-2021-03-03-21-44-20", "hyperparams": { "batch_size": 4, "learning_rate_multiplier": 0.1, "n_epochs": 4, "prompt_loss_weight": 0.1, }, "organization_id": "org-...", "result_files": [ { "id": "file-QQm6ZpqdNwAaVC3aSz5sWwLT", "object": "file", "bytes": 81509, "created_at": 1614807863, "filename": "compiled_results.csv", "purpose": "fine-tune-results" } ], "status": "succeeded", "validation_files": [], "training_files": [ { "id": "file-XGinujblHPwGLSztz8cPS8XY", "object": "file", "bytes": 1547276, "created_at": 1610062281, "filename": "my-data-train.jsonl", "purpose": "fine-tune-train" } ], "updated_at": 1614807865, }

4. Cancel fine-tune

http

copy code

POST https://api.openai.com/v1/fine-tunes/{fine_tune_id}/cancel

Immediately cancels the fine-tuning job.

Request a demo:

http

copy code

curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F/cancel \ -H "Authorization: Bearer $OPENAI_API_KEY"

Among them, fine_tune_id it is a character string of type string, which must be passed ; the ID of the fine-tuning job

response:

json

copy code

{ "id": "ft-xhrpBbvVUzYGo8oUO1FY4nI7", "object": "fine-tune", "model": "curie", "created_at": 1614807770, "events": [ { ... } ], "fine_tuned_model": null, "hyperparams": { ... }, "organization_id": "org-...", "result_files": [], "status": "cancelled", "validation_files": [], "training_files": [ { "id": "file-XGinujblHPwGLSztz8cPS8XY", "object": "file", "bytes": 1547276, "created_at": 1610062281, "filename": "my-data-train.jsonl", "purpose": "fine-tune-train" } ], "updated_at": 1614807789, }

5. List fine-tune events

http

copy code

GET https://api.openai.com/v1/fine-tunes/{fine_tune_id}/events

Get granular status updates for fine-tuning jobs.

Request a demo:

http

copy code

curl https://api.openai.com/v1/fine-tunes/ft-AF1WoRqd3aJAHsqc9NY7iL8F/events \ -H "Authorization: Bearer $OPENAI_API_KEY"

Among them, fine_tune_id it is a character string of type string, which must be passed ; the ID of the fine-tuning job;

response:

json

copy code

{ "object": "list", "data": [ { "object": "fine-tune-event", "created_at": 1614807352, "level": "info", "message": "Job enqueued. Waiting for jobs ahead to complete. Queue number: 0." }, { "object": "fine-tune-event", "created_at": 1614807356, "level": "info", "message": "Job started." }, { "object": "fine-tune-event", "created_at": 1614807861, "level": "info", "message": "Uploaded snapshot: curie:ft-acmeco-2021-03-03-21-44-20." }, { "object": "fine-tune-event", "created_at": 1614807864, "level": "info", "message": "Uploaded result files: file-QQm6ZpqdNwAaVC3aSz5sWwLT." }, { "object": "fine-tune-event", "created_at": 1614807864, "level": "info", "message": "Job succeeded." } ] }

Query parameters

stream （boolean，选填，Defaults to false）

Whether to event stream fine-tuning jobs.

If set to true, events will be readily available as data server-sent events . The stream terminates with a message when the job completes (successfully, cancelled, or failed) data：[DONE] .

If set to false, only events generated so far will be returned.

6. Delete fine-tune model

http

copy code

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

Delete the fine-tuned model. You must have the role of owner in the organization.

Request a demo:

http

copy code

curl https://api.openai.com/v1/models/curie:ft-acmeco-2021-03-03-21-44-20 \ -X DELETE \ -H "Authorization: Bearer $OPENAI_API_KEY"

Among them, model it is a string of type string, which must be passed ; the model to be deleted

response:

json

copy code

{ "id": "curie:ft-acmeco-2021-03-03-21-44-20", "object": "model", "deleted": true }

13. Moderations review

Given an input text, output whether the model classifies it as violating the OpenAI content policy.

Related guide: Moderations

1. Create moderation

http

copy code

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

Classify text to determine whether it violates OpenAI's content policy

Request a demo:

http

copy code

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." }'

response:

json

copy code

{ "id": "modr-5MWoLO", "model": "text-moderation-001", "results": [ { "categories": { "hate": false, "hate/threatening": true, "self-harm": false, "sexual": false, "sexual/minors": false, "violence": true, "violence/graphic": false }, "category_scores": { "hate": 0.22714105248451233, "hate/threatening": 0.4132447838783264, "self-harm": 0.005232391878962517, "sexual": 0.01407341007143259, "sexual/minors": 0.0038522258400917053, "violence": 0.9223177433013916, "violence/graphic": 0.036865197122097015 }, "flagged": true } ] }

Request body (detailed explanation of input parameters)

input (string or array, required)

the input text to classify

model （string，选填，Defaults to text-moderation-latest）

There are two content moderation models available: text-moderation-stable and text-moderation-latest.

By default, a model is used text-moderation-latest , which automatically upgrades over time. This ensures you are always using our most accurate models. If you use text-moderation-stable, we will provide an advanced notification before updating the model. text-moderation-stable may be slightly less accurate text-moderation-latest.

14. Engines engine

The engine endpoint is obsolete. Please use their replacement models . Learn more .

These endpoints describe and provide access to the various engines available in the API.

1. List engines <Desolate>

http

copy code

GET https://api.openai.com/v1/engines

Lists currently available (untuned) models and provides basic information about each such as owner and availability.

Request a demo:

http

copy code

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

response:

json

copy code

{ "data": [ { "id": "engine-id-0", "object": "engine", "owner": "organization-owner", "ready": true }, { "id": "engine-id-2", "object": "engine", "owner": "organization-owner", "ready": true }, { "id": "engine-id-3", "object": "engine", "owner": "openai", "ready": false }, ], "object": "list" }

2. Retrieve engine <Desolate>

http

copy code

GET https://api.openai.com/v1/engines/{engine_id}

Retrieves a model instance, providing basic information such as owner and availability.

Request a demo:

http

copy code

curl https://api.openai.com/v1/engines/text-davinci-003 \ -H "Authorization: Bearer $OPENAI_API_KEY"

Among them, engine_id it is a character string of type string, which must be passed ; the engine ID used for this request.

response:

json

copy code

{ "id": "text-davinci-003", "object": "engine", "owner": "openai", "ready": true }

15. Parameter details parameter details

Frequency and Existence Penalties

The frequency and presence penalties found in the Completions API can be used to reduce the likelihood of sampling duplicate token sequences. They are modified by directly adding contributions to logits (unnormalized log probabilities).

python

copy code

mu[j] -> mu[j] - c[j] * alpha_frequency - float(c[j] > 0) * alpha_presence

Where:

mu[j] is the logits of the j-th token
c[j] is how often that token was sampled prior to the current position
float(c[j] > 0) is 1 if c[j] > 0 and 0 otherwise
alpha_frequency is the frequency penalty coefficient
alpha_presence is the presence penalty coefficient

As we can see, the presence penalty is a one-time additive contribution applied to all tokens that have been sampled at least once, and the frequency penalty is a contribution proportional to how often a particular token has been sampled.

A reasonable value for the penalty factor is somewhere between 0.1 and 1 if the goal is only to slightly reduce repeated samples. If the aim is to strongly suppress duplicates, the factor can be increased to 2, but this may significantly reduce sample quality. Negative values can be used to increase the likelihood of recurrence.