OpenAI Chat Completions

兼容 OpenAI 官方 POST /v1/chat/completions 接口，根据对话历史创建模型响应，支持流式与非流式响应、工具调用、多模态输入等。

WARNING

建议使用官方原生接口。本接口为 OpenAI 原生格式，用于调用 GPT 系列模型最稳定。若通过本接口调用非 OpenAI 模型（如 Claude、Gemini），由代理侧进行格式转换，可能存在参数缺失或行为差异等问题。具体支持范围请咨询 FreeAPI。

请求

Endpoint

POST https://www.free-api.ai/api/v1/chat/completions

请求头

名称	必填	说明
Authorization	是	Bearer your-api-key
Content-Type	是	application/json

请求参数

字段	类型	必填	说明
model	string	是	模型 ID，例如 gpt-4o、gpt-5 等
messages	array	是	对话消息列表，每条消息包含 role 与 content
temperature	number	否	采样温度，范围 [0, 2]，默认 1
top_p	number	否	核采样参数，范围 [0, 1]，默认 1
n	integer	否	为每条输入生成的候选数量，默认 1
stream	boolean	否	是否使用流式响应，默认 false
stream_options	object	否	流式选项，例如 { "include_usage": true }
stop	string | string[]	否	停止序列
max_tokens	integer	否	最大生成 Token 数
max_completion_tokens	integer	否	最大补全 Token 数（推理模型推荐使用）
presence_penalty	number	否	出现惩罚，范围 [-2, 2]
frequency_penalty	number	否	频率惩罚，范围 [-2, 2]
logit_bias	object	否	Token 级别偏置
user	string	否	终端用户标识
tools	array	否	可调用的工具定义
tool_choice	string | object	否	工具选择策略，可选 none / auto / required，或指定具体函数
response_format	object	否	响应格式，例如 { "type": "json_object" }
seed	integer	否	随机种子
reasoning_effort	string	否	推理强度，low / medium / high，仅推理模型支持
modalities	string[]	否	模态，可选 text / audio
audio	object	否	音频输出配置，如 { "voice": "alloy", "format": "wav" }

消息结构

{
  "role": "user | assistant | system | tool",
  "content": "字符串或多模态数组"
}

请求示例

cURL

curl https://www.free-api.ai/api/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      { "role": "system", "content": "你是一个乐于助人的 AI 助手。" },
      { "role": "user", "content": "用一句话介绍一下你自己。" }
    ],
    "temperature": 0.7
  }'

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://www.free-api.ai/api/v1",
)

resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "你是一个乐于助人的 AI 助手。"},
        {"role": "user", "content": "用一句话介绍一下你自己。"},
    ],
)
print(resp.choices[0].message.content)

响应示例

非流式

{
  "id": "chatcmpl-xxxxxxxx",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是一个乐于助人的 AI 助手。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 12,
    "total_tokens": 36
  }
}

流式 (stream: true)

每条数据以 data: 开头，最后以 data: [DONE] 结束：

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"你好"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"！"},"finish_reason":null}]}

data: [DONE]

常见错误

HTTP 状态	说明
400	请求参数错误
401	鉴权失败，API Key 无效或已失效
429	请求频率限制
5xx	上游服务异常

错误响应体：

{
  "error": {
    "message": "错误描述",
    "type": "invalid_request_error",
    "code": "xxx"
  }
}