1. 引言
you-token文档
  • 引言
    • 获取令牌
    • 一个完整的请求案例
    • 关于缓存创建与命中
    • 联系客服
    • 定价说明
    • 常见接口错误类型说明
  • 模型介绍
    • GPT 系列
    • Claude 系列
    • Gemini 系列
    • DeepSeek系列
    • 百度文心一言
    • 阿里通义千问
  • 模型接口
    • 模型查询相关
      • 模型列表查询
      • 令牌用量查询
      • 获取账号信息
    • 聊天(Chat)
      • OpenAI
        • 基础聊天(ChatCompletions格式)
          • 基础文本对话
          • 流式响应
          • 内容补全(早期接口)
          • PDF文件分析
          • 代码生成(codex)
          • 结构化输出
          • 联网搜索
          • GPTs对话
        • 会话聊天(Responses格式)
          • 基础文本响应
          • 图像分析响应
          • 网络搜索工具
          • 文件搜索工具
          • 计算机模拟
          • 深度研究
          • 函数调用
          • 推理能力
      • Google Gemini
        • 文本聊天
        • 媒体识别
        • 视频理解
      • Anthropic Claude
        • 文本生成
        • 图片理解
        • 深度思考
        • 函数调用
        • 联网搜索
        • 带缓存创建的文本对话
    • 图像(Images)
      • Midjourney
        • 文生图(Imagine)接口
        • 按钮点击(Action)接口
        • 图片融合(Blend)接口
        • 窗口执行(Modal)接口
        • 图生文(Describe)接口
        • 缩短提示词(Shorten)接口
        • 换脸(FaceSwap)接口
        • 上传(upload)接口
        • 查询接口
        • 批量查询接口
        • 获取种子(Seed)接口
        • 编辑图片(Edit)接口
        • 生成视频(Video)接口
      • OpenAI
        • 图片生成 / gpt-image-1.5
        • 图片生成 / dall-e-3
        • 图片编辑 / edits接口
        • 图片变体生成
        • gpt-4-all(生成图片)
      • Google Gemini
        • OpenAI聊天格式
          • 图片生成(Nano-banana2)
          • 图片生成 / Imagen 4
        • Gemini原生格式
          • 图像生成
      • 豆包(Doubao)
        • 文生图(纯文本输入单图输出)
        • 图文生图(单图输入单图输出)
        • 多图融合(多图输入单图输出)
        • 组图输出(多图输出)
      • 阿里通义千问
        • 文生图-Z-Image
        • 文生图
        • 文生图V2版
        • 文生图V1版
    • 视频(Videos)
      • OpenAI兼容接口
        • Veo 视频生成(OpenAI 兼容格式)
        • 查询视频生成状态 Copy
        • luma
        • runway
      • Veo 3
        • Veo 视频生成
        • 查询视频生成状态
      • Sora-2
        • Sora-2(创建视频)
        • Sora2官方接口(Chat格式)
        • 查询视频(异步任务)
        • 获取视频内容
      • 阿里通义千问
        • 通义万相2.6(创建视频)
        • 查询视频(异步任务)
      • 豆包(Doubao)
        • 豆包-文生视频
        • 查询视频
      • 可灵AI(Kling)
        • 可灵AI-文生视频
        • 可灵AI-文生视频kling-video-o1
        • 可灵AI-图生视频
      • 即梦(Jimeng)
        • 即梦AI-文生视频S2.0Pro
    • 音频(Audio)
      • 原生OpenAI格式
        • 文本转语音 / TTS
        • 语音转文本 / whisper-1
        • 语音转文本 / gpt-4o-transcribe
        • 音频翻译
        • Audio接口 / 输出
        • Audio接口 / 输入
        • MiniMax语音合成TTS
        • 豆包语音2.0
      • 原生Gemini格式
    • 音乐(Music)
      • Suno
        • 生成歌曲
        • 生成歌词
        • 上传音乐
        • 歌曲拼接
        • 单个查询任务
        • 批量查询任务
      • Udio
        • Udio(Chat格式)
    • 嵌入(Embeddings)
      • 创建文本嵌入(OpenAI)
      • 批量创建嵌入(OpenAI)
      • 创建文本嵌入(Gemini)
    • 重排序 (Rerank)
      • Jina AI 重排序格式
      • Cohere 重排序格式
      • Xinference 重排序格式
    • 审查(Moderations)
      • 创建内容审核
  1. 引言

一个完整的请求案例

大模型通用接口 /v1/chat/completions 完整应用场景解析#

各位同学,大家好!今天我们聚焦大模型最通用的接口——/v1/chat/completions,结合一个真实的实操场景,从“提问触发”到“接口调用”,再到“结果解析”,完整拆解每一个环节,确保大家听完就能落地使用。
核心前提:该接口是大模型实现“多轮对话+精准响应”的核心接口,几乎所有大模型(OpenAI、字节跳动、百度文心等)都兼容该接口规范(仅部分参数有差异),是我们做大模型应用开发、接口调试的基础,也是日常工作中使用频率最高的接口。

一、本次实操应用场景定义#

场景:开发一个“大模型接口调试工具”的核心功能——用户输入自然语言提问,工具调用 /v1/chat/completions 接口,获取大模型的结构化回复,并展示给用户。
具体流程:
1.
用户操作:在工具输入框中输入提问(单轮提问,暂不涉及多轮,降低复杂度),比如:“请解释下 /v1/chat/completions 接口中 messages 参数的作用”;
2.
后端处理:接收用户提问,组装 /v1/chat/completions 接口的请求参数,发起HTTP POST请求;
3.
大模型响应:校验请求参数合法性,生成对应回复,通过接口返回给后端;
4.
前端展示:后端解析返回参数,提取核心回复内容,展示在工具的回复区域。
本次我们重点拆解“后端处理”和“大模型响应”两个核心环节,也就是接口的“请求参数”和“返回参数”。

二、场景触发:用户提问与请求触发逻辑#

2.1 用户提问(输入示例)#

用户输入(自然语言,无格式要求,由前端接收后传递给后端):
请解释下 /v1/chat/completions 接口中 messages 参数的作用,要求简洁明了,适配新手理解。

2.2 后端请求触发规则#

1.
请求方式:必须是HTTP POST(大模型接口均不支持GET请求,避免参数泄露+支持复杂参数传递);
2.
请求地址:以OpenAI为例,地址为 https://api.openai.com/v1/chat/completions(不同厂商仅域名不同,路径一致);
3.
请求头:必须携带身份校验和数据格式说明,核心头信息如下(后续参数部分详细说);
4.
触发时机:用户点击“提交提问”按钮后,后端立即组装参数发起请求,无需额外触发条件(实际开发中可增加“参数校验”“频率限制”前置逻辑)。

三、核心环节:接口请求参数详解(重点)#

请求参数是接口调用的“指令”,告诉大模型“要做什么、怎么做”,所有参数封装在POST请求的 body 中,格式为 JSON。
我们结合本次场景,给出“完整可直接调用”的参数示例,再逐一拆解每一个参数(分「必选参数」和「可选参数」,优先掌握必选)。

3.1 完整请求参数示例(JSON格式)#


{
  "model": "gpt-3.5-turbo",  // 必选:指定调用的大模型版本
  "messages": [               // 必选:对话历史/用户提问(核心参数)
    {
      "role": "user",         // 角色:user表示用户提问
      "content": "请解释下 /v1/chat/completions 接口中 messages 参数的作用,要求简洁明了,适配新手理解。"  // 用户具体提问内容
    }
  ],
  "temperature": 0.7,         // 可选:控制回复的随机性
  "max_tokens": 200,          // 可选:限制回复的最大token数
  "top_p": 1.0,               // 可选:控制回复的多样性(与temperature二选一即可)
  "n": 1,                     // 可选:指定返回多少条回复
  "stream": false,            // 可选:是否流式返回(本次场景用false,一次性获取完整回复)
  "stop": null                // 可选:指定回复的终止符(无需设置,默认无)
}

3.2 必选参数拆解(重中之重,必须掌握)#

3.2.1 model(必选)#

作用:指定你要调用的大模型版本/型号,不同模型的能力、响应速度、token成本不同。
常用取值(以OpenAI为例):
gpt-3.5-turbo:性价比最高,响应快,适合日常问答、接口调试、简单应用开发(本次场景选用);
gpt-4:能力最强,支持复杂逻辑、多轮对话、长文本处理,成本较高;
其他厂商取值:字节跳动ernie-bot-4、百度文心 ernie-4.0(均兼容该接口,仅model值不同)。
注意:必须填写大模型厂商支持的有效model值,否则接口会直接返回400错误(参数非法)。

3.2.2 messages(必选,核心中的核心)#

作用:传递「对话上下文」,告诉大模型“当前对话的历史的内容”,大模型基于该参数生成回复——这也是该接口叫“chat/completions”(对话补全)的原因。
参数格式:数组类型,每个数组元素是一个JSON对象,包含两个必选字段 role(角色)和 content(内容)。
核心角色(role)取值(3种,必须掌握):
1.
user:表示「用户」,content是用户的提问内容(本次场景仅用该角色,单轮对话);
2.
assistant:表示「大模型」,content是大模型之前的回复内容(多轮对话时需要携带,比如用户第二次提问,需要把第一次的user和assistant内容都放入messages);
3.
system:表示「系统指令」,content是对大模型的“全局约束”(比如“你是一个大模型接口讲师,回复必须简洁,适配新手”),优先级高于user的提问,会贯穿整个对话。
补充示例(多轮对话,帮助理解):

"messages": [
  {
    "role": "system",
    "content": "你是一个大模型接口讲师,回复必须简洁,适配新手,不使用复杂术语。"
  },
  {
    "role": "user",
    "content": "解释下messages参数的作用"
  },
  {
    "role": "assistant",
    "content": "messages是传递对话内容的参数,包含用户提问、大模型回复等,让大模型知道上下文。"
  },
  {
    "role": "user",
    "content": "那role字段有几种取值?"  // 第二次提问,多轮对话
  }
]

3.3 可选参数拆解(按需使用,重点掌握前3个)#

3.3.1 temperature(可选,默认0.7)#

作用:控制大模型回复的「随机性/创造性」,取值范围 0~2。
取值越接近0:回复越严谨、固定,重复率高(适合接口调试、知识问答,比如本次场景,我们要精准解释参数,取0.7即可);
取值越接近2:回复越有创造性、随机性,甚至可能偏离主题(适合文案创作、创意生成)。

3.3.2 max_tokens(可选,无默认值,建议设置)#

作用:限制大模型「回复的最大长度」,单位是token(1个中文汉字≈1.3个token,1个英文单词≈1个token)。
注意点:
token总数 = 提问内容的token数 + 回复内容的token数,不能超过当前model的最大token限制(比如gpt-3.5-turbo最大4096 token);
本次场景设置200,足够简洁解释参数,避免大模型回复过长,增加等待时间和成本。

3.3.3 stream(可选,默认false)#

作用:控制回复的「返回方式」。
false(本次场景选用):一次性返回完整回复,适合简单问答、接口调试,后端解析简单;
true:流式返回,逐字/逐句返回回复(类似ChatGPT网页端的打字效果),适合长文本回复,提升用户体验,后端需要做流式解析。

3.3.4 其他可选参数(了解即可)#

top_p:取值0~1,与temperature作用类似,控制回复多样性,二选一即可(不建议同时设置);
n:指定返回多少条回复,默认1(一般无需修改,多回复会增加成本);
stop:指定终止符,比如设置为“谢谢”,大模型回复到“谢谢”就会停止(极少用)。

3.4 请求头参数(必选,容易遗漏)#

发起POST请求时,请求头必须携带以下信息,否则接口会返回401错误(权限不足):

{
  "Content-Type": "application/json",  // 必选:指定请求体格式为JSON
  "Authorization": "Bearer sk-xxxxxxxxxxxxxxxx"  // 必选:身份校验,sk是大模型厂商提供的API密钥
}
重点提醒:API密钥(sk)是敏感信息,后端调用时必须加密存储,禁止暴露在前端(避免泄露后被恶意调用,产生高额费用)。

四、核心环节:接口返回参数详解(重点)#

当大模型校验请求参数合法后,会返回JSON格式的响应结果,我们需要从返回参数中「提取用户需要的核心回复内容」(即assistant的content)。
结合本次场景,给出「完整返回参数示例」,再逐一拆解核心字段。

4.1 完整返回参数示例(JSON格式)#


{
  "id": "chatcmpl-8xxxxxxxxxxxxxxxxxxxxxxx",  // 本次请求的唯一ID(用于调试、报错排查)
  "object": "chat.completion",                // 接口对象类型(固定值,无需关注)
  "created": 1718xxxxxxx,                     // 请求创建时间(时间戳,单位:秒)
  "model": "gpt-3.5-turbo-0613",              // 实际调用的大模型版本(可能与请求时的model略有差异,厂商适配)
  "choices": [                                // 回复列表(核心字段,与请求时的n参数对应,n=1则只有1个元素)
    {
      "message": {
        "role": "assistant",                  // 角色:assistant表示大模型的回复
        "content": "messages是/v1/chat/completions接口的核心参数,用于传递对话上下文,包含用户提问、大模型之前的回复等内容,让大模型能结合上下文生成精准回复,适配新手理解。"  // 核心回复内容
      },
      "finish_reason": "stop",                // 回复终止原因(stop表示正常终止)
      "index": 0                               // 回复索引(n=1时为0,多回复时依次递增)
    }
  ],
  "usage": {                                  // token使用情况(成本核算、限流依据)
    "prompt_tokens": 58,                      // 提问内容消耗的token数
    "completion_tokens": 86,                  // 回复内容消耗的token数
    "total_tokens": 144                       // 总消耗token数
  }
}

4.2 核心返回字段拆解(必须掌握)#

4.2.1 choices(核心中的核心)#

作用:存储大模型的回复列表,我们需要的「核心回复内容」就在这个字段里。
重点拆解choices[0](n=1时,只有一个元素):
message:大模型的回复对象,包含 role(assistant)和 content(核心回复文本)——我们前端展示、后端返回给用户的,就是这个content字段;
finish_reason:回复终止原因(重点关注,用于排查异常):
stop:正常终止,回复完整(本次场景的情况);
length:因请求时设置了max_tokens,回复被截断(需增大max_tokens);
content_filter:回复包含敏感内容,被内容审核过滤(需检查用户提问或调整system指令);
null:回复未完成(一般是stream=true时,还在流式返回)。

4.2.2 usage(重点)#

作用:返回本次接口调用的「token消耗情况」,用于两个核心场景:
1.
成本核算:大模型按token收费,total_tokens就是本次调用的计费依据;
2.
限流排查:如果调用频繁出现token不足,需检查prompt_tokens(提问内容是否过长)或max_tokens(设置是否过大)。

4.2.3 其他字段(了解即可)#

id:本次请求的唯一ID,当接口报错、回复异常时,可通过该ID联系大模型厂商排查问题;
created:时间戳,可用于记录请求时间(转换为本地时间即可);
object:固定值chat.completion,无需关注,仅用于接口标识。

五、实操注意事项(避坑重点,同行必看)#

这部分是我们日常开发中最容易踩坑的地方,结合接口特性和实际经验,总结6个核心注意事项,每一个都对应真实场景的问题。

5.1 权限与密钥相关(最容易报错)#

API密钥(sk)必须正确,且未过期、未被禁用(否则返回401错误);
密钥必须后端存储、后端调用,禁止暴露在前端代码(比如Vue、React的前端页面),否则会被恶意爬取,产生高额费用;

5.2 参数格式相关(最容易忽略)#

请求体必须是JSON格式,且Content-Type请求头必须设置为application/json(否则返回400错误);
messages参数是数组类型,每个元素必须包含role和content两个字段,缺一不可(否则返回400错误);
role字段仅支持user、assistant、system三个取值,输入其他值会返回400错误;
max_tokens的取值不能超过当前model的最大token限制(比如gpt-3.5-turbo最大4096),否则返回400错误。

5.3 token相关(成本+限流避坑)#

token总数 = prompt_tokens + completion_tokens,必须≤model的最大token限制,否则会被截断或报错;
多轮对话时,messages数组会累积(包含所有user和assistant的内容),token数会逐渐增加,需定期清理无效的对话历史,避免token溢出;
建议给max_tokens设置合理的值(比如日常问答设置200~500),既避免回复过长,也减少不必要的token消耗(降低成本)。

5.4 响应解析相关(避免异常)#

解析返回参数时,优先判断choices[0].finish_reason是否为stop,若为length,需提示用户“回复被截断,请增大max_tokens”;若为content_filter,需提示用户“提问包含敏感内容,请调整”;
stream=true时,返回的是流式数据(不是完整JSON),后端需要用流式解析(比如Node.js的stream模块),否则会解析失败;
若返回参数中没有choices字段,大概率是请求参数错误或权限问题,可先检查model、messages参数和API密钥。

5.5 兼容性相关(多厂商适配)#

不同大模型厂商的 /v1/chat/completions 接口,核心参数(model、messages)一致,但部分可选参数有差异(比如字节跳动的接口支持temperature范围0~1);
切换大模型厂商时,只需修改3处:请求地址、model值、API密钥,核心的参数组装、返回解析逻辑可复用(这也是该接口通用的核心优势)。

5.6 异常处理相关(实操必备)#

网络异常:需添加请求超时处理(比如设置10秒超时),超时后提示用户“接口调用超时,请重试”;
报错处理:捕获接口返回的错误码(400、401、403、500等),给出明确的错误提示(比如401提示“API密钥错误”),方便调试;
频率限制:大部分厂商会对API调用频率进行限制(比如每分钟60次),需添加频率控制逻辑,避免触发限流(返回429错误)。

六、场景复盘与落地总结#

各位同行,我们今天结合“接口调试工具”的核心场景,完整拆解了 /v1/chat/completions 接口的全流程:
1.
提问触发:用户输入自然语言,前端传递给后端;
2.
参数组装:重点关注必选参数(model、messages)和请求头,按需设置可选参数;
3.
接口调用:发起POST请求,携带正确的参数和密钥;
4.
结果解析:从choices字段中提取assistant的content,判断finish_reason是否正常;
5.
避坑重点:密钥安全、参数格式、token限制、异常处理。
核心总结:该接口的核心价值是「通用、简洁、可扩展」——通用是因为几乎所有大模型都兼容,简洁是因为核心参数只有2个,可扩展是因为支持多轮对话、流式返回等多种需求,是我们做大模型应用开发的“基石接口”。
后续大家在实操中,只要掌握“必选参数+核心返回字段+注意事项”,就能轻松应对大部分接口调用场景,遇到问题可通过返回的错误码、请求ID快速排查。
(注:文档部分内容可能由 AI 生成)
修改于 2026-03-16 14:55:01
上一页
获取令牌
下一页
关于缓存创建与命中
Built with