> ## Documentation Index > Fetch the complete documentation index at: https://docs.pinducloud.com/llms.txt > Use this file to discover all available pages before exploring further. # API 对接文档 # 品度云 API 对接文档 品度云提供 OpenAI 兼容格式的模型调用能力，接入方可按照标准 `chat/completions` 方式调用文本对话模型。 ## 基础信息 ### Base URL ```text theme={null} http://101.37.203.77 ``` 接口完整地址由 `Base URL + 接口路径` 组成，例如： ```text theme={null} http://101.37.203.77/v1/chat/completions ``` ### 鉴权方式 请求时需在 Header 中携带 API Key： ```http theme={null} Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` 请将示例中的 `YOUR_API_KEY` 替换为实际分配的密钥。 ## 支持模型 | 模型名称 | 调用时 `model` 参数 | 说明 | | ----------------- | ------------------- | ------------------- | | glm-5.1 | `glm-5.1` | 通用对话、文本生成、问答、摘要等场景 | | minimax-m2.7 | `minimax-m2.7` | 适合中文创作、对话、内容生成等场景 | | kimi-k2.5 | `kimi-k2.5` | 适合长文本理解、总结、知识问答等场景 | | kimi-k2.6 | `kimi-k2.6` | 适合长文本理解、总结、知识问答等场景 | | deepseek-v4-pro | `deepseek-v4-pro` | 适合代码、推理和复杂问答场景 | | deepseek-v4-flash | `deepseek-v4-flash` | 适合快速响应、轻量推理和高并发调用场景 | 如平台实际分配的模型 ID 与上表不同，请以品度云后台或技术支持提供的模型 ID 为准。 ## 聊天补全接口 ### 请求地址 ```http theme={null} POST /v1/chat/completions ``` 完整地址： ```text theme={null} http://101.37.203.77/v1/chat/completions ``` ### 请求参数 | 参数 | 类型 | 必填 | 说明 | | ------------------- | ------- | -- | ----------------------------- | | `model` | string | 是 | 模型名称，例如 `glm-5.1`、`kimi-k2.6` | | `messages` | array | 是 | 对话消息列表 | | `temperature` | number | 否 | 随机性，常用范围 `0` 到 `2`，默认可填 `0.7` | | `top_p` | number | 否 | 核采样参数，常用范围 `0` 到 `1` | | `max_tokens` | number | 否 | 最大输出 token 数 | | `stream` | boolean | 否 | 是否开启流式输出，默认 `false` | | `presence_penalty` | number | 否 | 话题新颖度惩罚参数 | | `frequency_penalty` | number | 否 | 重复内容惩罚参数 | ### `messages` 格式 | 字段 | 类型 | 必填 | 说明 | | --------- | ------ | -- | ----------------------------------- | | `role` | string | 是 | 消息角色，可选 `system`、`user`、`assistant` | | `content` | string | 是 | 消息内容 | | `role` | 说明 | | ----------- | ---------------------- | | `system` | 系统提示词，用于设定模型身份、回答风格和约束 | | `user` | 用户输入内容 | | `assistant` | 模型历史回复，用于多轮对话上下文 | ## 非流式调用 ### curl 示例 ```bash theme={null} curl http://101.37.203.77/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "glm-5.1", "messages": [ { "role": "system", "content": "你是一个专业、简洁的中文助手。" }, { "role": "user", "content": "请用三句话介绍品度云中转站。" } ], "temperature": 0.7, "max_tokens": 800 }' ``` ### JavaScript 示例 ```js theme={null} const response = await fetch("http://101.37.203.77/v1/chat/completions", { method: "POST", headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ model: "kimi-k2.6", messages: [ { role: "system", content: "你是一个专业、简洁的中文助手。" }, { role: "user", content: "帮我写一段产品介绍。" } ], temperature: 0.7, max_tokens: 1000 }) }); const data = await response.json(); console.log(data.choices[0].message.content); ``` ### Python 示例 ```python theme={null} import requests url = "http://101.37.203.77/v1/chat/completions" headers = { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json", } payload = { "model": "deepseek-v4-pro", "messages": [ {"role": "system", "content": "你是一个专业、简洁的中文助手。"}, {"role": "user", "content": "请解释什么是 API 中转站。"}, ], "temperature": 0.7, "max_tokens": 1000, } response = requests.post(url, headers=headers, json=payload, timeout=60) response.raise_for_status() data = response.json() print(data["choices"][0]["message"]["content"]) ``` ## 流式调用 流式输出适合聊天机器人、打字机效果、长文本生成等场景。开启方式是在请求体中设置： ```json theme={null} { "stream": true } ``` ### curl 流式示例 ```bash theme={null} curl http://101.37.203.77/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "minimax-m2.7", "messages": [ { "role": "user", "content": "请写一段 200 字左右的品牌文案。" } ], "stream": true, "temperature": 0.8 }' ``` ## 响应格式 ### 非流式响应示例 ```json theme={null} { "id": "chatcmpl_xxx", "object": "chat.completion", "created": 1710000000, "model": "glm-5.1", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "这里是模型返回的回答内容。" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 20, "completion_tokens": 30, "total_tokens": 50 } } ``` ### 常用响应字段 | 字段 | 说明 | | ---------------------------- | ----------------------- | | `id` | 本次请求的唯一 ID | | `object` | 返回对象类型 | | `created` | 创建时间戳 | | `model` | 实际调用的模型 | | `choices` | 模型输出结果列表 | | `choices[0].message.content` | 非流式场景下的最终回复内容 | | `choices[0].finish_reason` | 结束原因，例如 `stop`、`length` | | `usage` | token 用量信息 | ## 错误响应 ### 错误格式示例 ```json theme={null} { "error": { "message": "Invalid API key", "type": "authentication_error", "code": "invalid_api_key" } } ``` ### 常见 HTTP 状态码 | 状态码 | 说明 | 排查建议 | | --------------------- | ------- | -------------------------------- | | `400` | 请求参数错误 | 检查 JSON 格式、模型名称、`messages` 格式 | | `401` | 鉴权失败 | 检查 API Key 是否正确、是否带有 `Bearer` 前缀 | | `403` | 无权限访问 | 检查账号权限、模型权限或额度状态 | | `404` | 接口不存在 | 检查请求地址和接口路径是否正确 | | `429` | 请求过于频繁 | 降低并发或联系平台调整限额 | | `500` | 服务内部错误 | 稍后重试或联系品度云技术支持 | | `502` / `503` / `504` | 上游或网关异常 | 稍后重试，必要时切换模型或联系技术支持 | ## 多轮对话 多轮对话需要将历史消息一起传入 `messages`，模型会根据上下文生成回复。 ```json theme={null} { "model": "kimi-k2.6", "messages": [ { "role": "system", "content": "你是一个专业、简洁的中文助手。" }, { "role": "user", "content": "什么是 API 中转站？" }, { "role": "assistant", "content": "API 中转站是用于统一转发、鉴权、管理和调用不同模型服务的接口层。" }, { "role": "user", "content": "它适合哪些业务场景？" } ], "temperature": 0.7 } ``` ## 接入建议 * 生产环境建议设置请求超时时间，例如 `60` 秒到 `180` 秒。 * 建议业务侧保存请求日志、响应状态码和错误信息，方便排查问题。 * 对用户输入内容做好长度控制，避免超过模型上下文限制。 * 对重要业务场景建议增加重试机制，但不要无限重试。 * 流式输出时需要按服务端事件流或文本分片方式逐段解析。 * 当前 Base URL 使用 HTTP 协议，如涉及敏感数据，建议确认是否可提供 HTTPS 地址。 * API Key 应保存在服务端环境变量或密钥管理系统中，不要暴露在前端页面或客户端代码中。 ## 环境变量配置示例 ```bash theme={null} PINGDU_BASE_URL=http://101.37.203.77 PINGDU_API_KEY=YOUR_API_KEY PINGDU_MODEL=glm-5.1 ``` ## 最小可用请求 ```bash theme={null} curl http://101.37.203.77/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "glm-5.1", "messages": [ { "role": "user", "content": "你好，请简单介绍一下你自己。" } ] }' ```