OpenAI API格式 · Forrest

OpenAI API 格式详解

OpenAI API 提供了多种端点，用于处理文本生成、嵌入、图像、音频等任务

每个端点都支持通过 HTTP POST/GET 等方法调用，需要在请求头中包含 Authorization: Bearer YOUR_API_KEY 和 Content-Type: application/json（除文件上传外）

1. Chat Completions（聊天完成）

此端点用于生成对话响应，支持多模态输入（如文本、图像、音频）

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

请求体 (JSON):

参数	类型	必需	默认值	描述
messages	array	是	-	对话消息列表，每个消息包含 role (system/user/assistant) 和 content，支持多模态
model	string	是	-	模型 ID，如 gpt-4o
frequency_penalty	number	否	0	频率惩罚 (-2.0 到 2.0)，避免重复回答同样的token
logprobs	boolean	否	false	是否返回对数概率
max_completion_tokens	integer	否	-	最大生成令牌数
n	integer	否	1	生成的选择数
presence_penalty	number	否	0	存在惩罚 (-2.0 到 2.0)
response_format	object	否	-	输出格式，如 { “type”: “json_schema” }
stream	boolean	否	false	是否流式响应
temperature	number	否	1	采样温度 (0 到 2)
tools	array	否	-	工具列表（如函数调用）
top_p	number	否	1	核采样阈值

响应 (JSON):
- id: 完成 ID
- choices: 数组，包含生成的 message、finish_reason 等
- usage: 令牌使用统计，包括 prompt_tokens、completion_tokens

示例请求:

{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "Hello!"}]
}

示例响应:

{
  "id": "chatcmpl-123",
  "choices": [{"message": {"role": "assistant", "content": "Hi!"}}],
  "usage": {"prompt_tokens": 10, "completion_tokens": 5}
}

2. Embeddings（嵌入）

用于生成文本嵌入向量

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

请求体 (JSON):

参数	类型	必需	默认值	描述
input	string/array	是	-	输入文本或数组
model	string	是	-	模型，如 text-embedding-ada-002
dimensions	integer	否	-	输出维度（特定模型支持）
encoding_format	string	否	float	输出格式 (float/base64)

响应 (JSON):
- data: 嵌入数组，每个包含 embedding (浮点数组)
- usage: 令牌使用

示例请求:

{
  "input": "Your text here",
  "model": "text-embedding-ada-002"
}

示例响应:

{
  "data": [{"embedding": [0.002, -0.009, ...]}],
  "usage": {"prompt_tokens": 8}
}

3. Fine-tuning（微调）

微调的核心是“在基础模型的基础上，用小数据集做少量参数更新”

基础模型已掌握海量通用知识，微调只需调整部分与任务相关的参数（如注意力层的权重），避免覆盖原有知识

OpenAI 的微调过程包括加载基础模型，使用上传的训练数据通过梯度下降更新参数，限制更新范围和幅度

训练完成后，生成专属微调模型，通过 API 调用以融入数据特性

用于创建和管理微调作业

主要子端点:
- 创建: POST /fine_tuning/jobs
- 列表: GET /fine_tuning/jobs
- 获取: GET /fine_tuning/jobs/{id}
- 取消: POST /fine_tuning/jobs/{id}/cancel
- 事件: GET /fine_tuning/jobs/{id}/events

创建请求体 (JSON):

参数	类型	必需	默认值	描述
model	string	是	-	基础模型，如 gpt-4o-mini
training_file	string	是	-	训练文件 ID
validation_file	string	否	-	验证文件 ID
hyperparameters	object	否	-	超参数，如 n_epochs

响应 (JSON): fine_tuning.job 对象，包括 id、status、fine_tuned_model 等

示例创建请求:

{
  "training_file": "file-abc123",
  "model": "gpt-4o-mini"
}

示例响应:

{
  "id": "ftjob-abc123",
  "status": "queued"
}

4. Images（图像）

支持生成、编辑和变体

生成端点: POST /images/generations
请求体 (JSON):

参数类型必需默认值描述

prompt string 是 - 描述文本

model string 否 dall-e-2 模型，如 dall-e-3

n integer 否 1 生成图像数

size string 否 1024x1024 尺寸
响应 (JSON): data 数组，包含图像 URL 或 base64
示例请求:
```
{
  "prompt": "A cute cat",
  "n": 1
}
```
编辑/变体类似，但使用 multipart/form-data 上传图像

参数	类型	必需	默认值	描述
prompt	string	是	-	描述文本
model	string	否	dall-e-2	模型，如 dall-e-3
n	integer	否	1	生成图像数
size	string	否	1024x1024	尺寸

5. Audio（音频）

支持语音合成、转录和翻译

语音合成端点: POST /audio/speech
请求体 (JSON):

参数类型必需默认值描述

input string 是 - 文本

model string 是 - 模型，如 tts-1

voice string 是 - 声音，如 alloy
响应: 音频文件内容
转录/翻译类似，使用 multipart/form-data 上传音频

参数	类型	必需	默认值	描述
input	string	是	-	文本
model	string	是	-	模型，如 tts-1
voice	string	是	-	声音，如 alloy

6. Moderations（审核）

用于内容分类

端点: POST /moderations
请求体 (JSON):

参数类型必需默认值描述

input string/array 是 - 输入内容

model string 否 omni-moderation-latest 模型
响应 (JSON): results 数组，包含类别标志和分数

参数	类型	必需	默认值	描述
input	string/array	是	-	输入内容
model	string	否	omni-moderation-latest	模型

7. Assistants（助手）（已弃用，将于2026年移除，推荐 Responses API）

用于创建和管理助手

创建端点: POST /assistants
请求体 (JSON): 类似 Chat，包括 instructions、tools 等
响应: 助手对象

8. Files（文件）

用于上传和管理文件

上传端点: POST /files (multipart/form-data)
请求: file 和 purpose
响应: 文件对象，包括 id、bytes

9. Batch（批量）

用于批量处理请求

创建端点: POST /batches
请求体 (JSON):

参数类型必需默认值描述

input_file_id string 是 - 输入文件 ID

endpoint string 是 - 目标端点，如 /chat/completions

completion_window string 是 - “24h”
响应: 批量对象，包括 status、request_counts

参数	类型	必需	默认值	描述
input_file_id	string	是	-	输入文件 ID
endpoint	string	是	-	目标端点，如 /chat/completions
completion_window	string	是	-	“24h”

注意：所有端点支持错误处理（如 429 限速），并可通过 user 参数跟踪用户