Chat-Completions API 使用指南

本文档详细说明了如何使用 Chat-Completions API 进行各种 AI 对话和文本生成任务。该 API 兼容 OpenAI 格式，支持多种模型，包括 GPT、Claude、Gemini 等主流 AI 模型。

官方文档：https://platform.openai.com/docs/api-reference/chat

📝 简介

Chat-Completions API 是一个强大且灵活的接口，提供了访问最先进的 AI 模型的简单方式，支持：

💬 文本对话：自然语言问答和对话

🖼️ 图像分析：多模态内容理解

🔄 流式响应：实时流式输出

🛠️ 函数调用：工具集成和自动化

📊 结构化输出：JSON 格式输出

🎯 多种模型：支持各大厂商的主流模型

🔧 接口定义

端点：/v1/chat/completions

方法：POST

认证：Bearer Token

格式：application/json

🔐 鉴权方法

所有请求都需要在 HTTP Header 中包含 Authorization 字段：

请将 YOUR_API_KEY 替换为您在平台生成的有效 API 密钥。

💡 请求示例

基础文本对话 ✅

最简单的文本问答场景：

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "你好，请介绍一下人工智能的发展历史"
        }
    ],
    "max_tokens": 1000,
    "temperature": 0.7
}

图像分析对话 ✅

支持图像输入的多模态对话：

{
    "model": "gemini-2.5-flash-all",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "请描述这张图片中的内容"
                },
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD..."
                    }
                }
            ]
        }
    ],
    "max_tokens": 500
}

流式响应 ✅

实现实时流式输出：

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "请写一首关于春天的诗"
        }
    ],
    "stream": true,
    "stream_options": {
        "include_usage": true
    }
}

函数调用 ✅

集成外部工具和函数：

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "今天北京的天气怎么样？"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "获取指定城市的天气信息",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {
                            "type": "string",
                            "description": "城市名称"
                        }
                    },
                    "required": ["city"]
                }
            }
        }
    ],
    "tool_choice": "auto"
}

JSON 模式输出 ✅

强制模型输出结构化 JSON：

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "system",
            "content": "你是一个数据提取助手，请将用户输入的信息提取为JSON格式"
        },
        {
            "role": "user",
            "content": "张三，男，25岁，软件工程师，住在北京市朝阳区"
        }
    ],
    "response_format": {
        "type": "json_object"
    }
}

📮 请求参数详解

核心参数

参数	类型	必需	默认值	描述
`model`	string	是	-	指定使用的模型名称
`messages`	array	是	-	对话消息列表
`max_tokens`	integer	否	-	生成内容的最大 Token 数
`temperature`	number	否	1	控制输出随机性 (0-2)
`top_p`	number	否	1	核采样参数 (0-1)
`n`	integer	否	1	生成响应的数量
`stream`	boolean	否	false	是否启用流式输出

messages 参数详解

消息数组中每个对象的结构：

{
    "role": "user|assistant|system|tool",
    "content": "消息内容",
    "name": "可选的发送者名称",
    "tool_calls": "工具调用信息",
    "tool_call_id": "工具调用ID"
}

角色说明：

system：系统提示，定义 AI 的行为和角色

user：用户输入的消息

assistant：AI 助手的回复

tool：工具调用的返回结果

高级参数

参数	类型	描述
`stop`	string/array	停止生成的序列
`presence_penalty`	number	存在惩罚 (-2.0 到 2.0)
`frequency_penalty`	number	频率惩罚 (-2.0 到 2.0)
`logit_bias`	object	Token 生成偏置
`user`	string	最终用户标识符
`seed`	integer	确定性采样种子
`response_format`	object	输出格式控制
`tools`	array	可用工具列表
`tool_choice`	string/object	工具选择策略

📥 响应格式

标准响应

{
    "id": "chatcmpl-8XYZ123",
    "object": "chat.completion",
    "created": 1699000000,
    "model": "gpt-4o-2024-05-13",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "这是 AI 的回复内容"
            },
            "logprobs": null,
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 15,
        "completion_tokens": 25,
        "total_tokens": 40,
        "completion_tokens_details": {
            "reasoning_tokens": 0
        }
    },
    "system_fingerprint": "fp_abc123"
}

流式响应

data: {"id":"chatcmpl-8XYZ123","object":"chat.completion.chunk","created":1699000000,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":"你好"},"logprobs":null,"finish_reason":null}]}

data: {"id":"chatcmpl-8XYZ123","object":"chat.completion.chunk","created":1699000000,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"！"},"logprobs":null,"finish_reason":null}]}

data: {"id":"chatcmpl-8XYZ123","object":"chat.completion.chunk","created":1699000000,"model":"gpt-4o","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}

data: [DONE]

finish_reason 说明

值	描述
`stop`	模型自然停止或遇到停止序列
`length`	达到最大 Token 限制
`tool_calls`	模型调用了工具
`content_filter`	内容被过滤

💻 代码示例

Python 示例

基础对话

图像分析

流式输出

Node.js 示例

基础对话

函数调用

cURL 示例

基础请求

流式请求

Go 示例

🚀 使用场景详解

1. 智能客服

2. 内容创作

3. 代码助手

4. 文档分析

⚙️ 最佳实践

1. 系统提示优化

好的系统提示示例：

{
    "role": "system",
    "content": "你是一个专业的Python编程导师。请遵循以下原则：\n1. 提供清晰、可执行的代码示例\n2. 解释代码的工作原理\n3. 指出潜在的问题和改进建议\n4. 使用简洁明了的语言"
}

2. 温度参数调优

场景	推荐温度	说明
事实问答	0.1-0.3	需要准确性
创意写作	0.7-0.9	需要创造性
代码生成	0.2-0.4	平衡准确性和灵活性
翻译任务	0.1-0.2	需要一致性

3. Token 使用优化

4. 错误处理

5. 流式输出处理

🔍 模型选择指南

主流模型对比

模型	特点	适用场景	成本
GPT-4o	多模态，性能强	复杂推理，图像分析	高
GPT-3.5-turbo	平衡性能和成本	一般对话，内容生成	中
Claude-3	长文本处理强	文档分析，长对话	中高
Gemini Pro	Google 生态	多模态任务	中

模型选择建议

🚨 常见错误和解决方案

1. 认证错误 (401)

{
    "error": {
        "message": "Invalid API key provided",
        "type": "invalid_request_error",
        "code": "invalid_api_key"
    }
}

解决方案：

检查 API 密钥是否正确

确认密钥格式：Bearer sk-xxxxx

验证密钥是否过期

2. 请求过大 (413)

{
    "error": {
        "message": "Request too large",
        "type": "invalid_request_error",
        "code": "request_too_large"
    }
}

解决方案：

减少输入文本长度

优化图像大小

分批处理长文档

3. 速率限制 (429)

{
    "error": {
        "message": "Rate limit exceeded",
        "type": "rate_limit_error", 
        "code": "rate_limit_exceeded"
    }
}

解决方案：

实现指数退避重试

控制并发请求数

升级到更高级别的套餐

4. 模型不可用 (404)

{
    "error": {
        "message": "Model not found",
        "type": "invalid_request_error",
        "code": "model_not_found"
    }
}

解决方案：

检查模型名称拼写

确认模型是否支持

使用备用模型

📊 性能监控

1. Token 使用统计

2. 响应时间监控

🔒 安全注意事项

1. API 密钥安全

2. 输入验证

3. 内容过滤

📚 相关资源

官方文档

🔧 模型列表和定价

📊 使用统计面板

💡 高级技巧

1. 对话上下文管理

2. 批量处理

3. 智能重试机制

🎯 总结

Chat-Completions API 是一个功能强大且灵活的接口，支持多种 AI 模型和使用场景。通过本指南，您可以：

✅ 掌握基础用法 - 了解接口调用方法和参数配置
✅ 实现高级功能 - 支持多模态、流式输出、函数调用等
✅ 优化性能 - 合理选择模型、管理 Token、处理错误
✅ 确保安全 - 保护 API 密钥、验证输入、过滤内容
✅ 监控使用 - 跟踪性能指标、统计使用情况

遵循本指南的最佳实践，您将能够构建稳定、高效的 AI 应用程序。如有任何问题，请参考相关资源或联系技术支持。

Chat-Completions API 使用指南

📝 简介#

🔧 接口定义#

🔐 鉴权方法#

💡 请求示例#

基础文本对话 ✅#

图像分析对话 ✅#

流式响应 ✅#

函数调用 ✅#

JSON 模式输出 ✅#

📮 请求参数详解#

核心参数#

messages 参数详解#

高级参数#

📥 响应格式#

标准响应#

流式响应#

finish_reason 说明#

💻 代码示例#

Python 示例#

基础对话#

图像分析#

流式输出#

Node.js 示例#

基础对话#

函数调用#

cURL 示例#

基础请求#

流式请求#

Go 示例#

🚀 使用场景详解#

1. 智能客服#

2. 内容创作#

3. 代码助手#

4. 文档分析#

⚙️ 最佳实践#

1. 系统提示优化#

2. 温度参数调优#

3. Token 使用优化#

4. 错误处理#

5. 流式输出处理#

🔍 模型选择指南#

主流模型对比#

模型选择建议#

🚨 常见错误和解决方案#

1. 认证错误 (401)#

2. 请求过大 (413)#

3. 速率限制 (429)#

4. 模型不可用 (404)#

📊 性能监控#

1. Token 使用统计#

2. 响应时间监控#

🔒 安全注意事项#

1. API 密钥安全#

2. 输入验证#

3. 内容过滤#

📚 相关资源#

官方文档#

💡 高级技巧#

1. 对话上下文管理#

2. 批量处理#

3. 智能重试机制#

🎯 总结#

📝 简介

🔧 接口定义

🔐 鉴权方法

💡 请求示例

基础文本对话 ✅

图像分析对话 ✅

流式响应 ✅

函数调用 ✅

JSON 模式输出 ✅

📮 请求参数详解

核心参数

messages 参数详解

高级参数

📥 响应格式

标准响应

流式响应

finish_reason 说明

💻 代码示例

Python 示例

基础对话

图像分析

流式输出

Node.js 示例

基础对话

函数调用

cURL 示例

基础请求

流式请求

Go 示例

🚀 使用场景详解

1. 智能客服

2. 内容创作

3. 代码助手

4. 文档分析

⚙️ 最佳实践

1. 系统提示优化

2. 温度参数调优

3. Token 使用优化

4. 错误处理

5. 流式输出处理

🔍 模型选择指南

主流模型对比

模型选择建议

🚨 常见错误和解决方案

1. 认证错误 (401)

2. 请求过大 (413)

3. 速率限制 (429)

4. 模型不可用 (404)

📊 性能监控

1. Token 使用统计

2. 响应时间监控

🔒 安全注意事项

1. API 密钥安全

2. 输入验证

3. 内容过滤

📚 相关资源

官方文档

💡 高级技巧

1. 对话上下文管理

2. 批量处理

3. 智能重试机制

🎯 总结