> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fineone-ai.fineres.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 模型接口

> 使用 DeepSeek、GLM、Kimi、Qwen 等平台可用模型发起对话请求

FineOneAI 提供兼容 OpenAI Chat Completions 格式的统一对话接口。当前平台主要提供国内模型服务，包括 DeepSeek、GLM、Kimi 和 Qwen。具体可用模型 ID、权限和参数支持以 FineOneAI 控制台的模型页面为准。

## 接口地址

```text theme={null}
POST https://fineone-ai.fineres.com/v1/chat/completions
```

这是完整请求 URL。调用时不要再重复拼接 `/v1` 或 `/chat/completions`。

## 认证方式

在请求头中使用 FineOneAI API Key：

```http theme={null}
Authorization: Bearer YOUR_FINEONE_API_KEY
Content-Type: application/json
```

请在控制台创建 API Key，并将其保存在服务端环境变量或密钥管理系统中。不要把完整密钥写入公开代码、浏览器前端或日志。

## 请求体

最小请求体如下：

```json theme={null}
{
  "model": "在平台模型页面查看准确模型 ID",
  "messages": [
    {
      "role": "user",
      "content": "你好，请介绍一下 FineOneAI。"
    }
  ]
}
```

### 字段说明

| 字段 | 类型 | 必填 | 说明 |
| - | - | - | - |
| `model` | string | 是 | 平台模型页面显示的准确模型 ID。不要仅填写 `deepseek`、`glm`、`kimi` 或 `qwen`，除非页面明确提供该 ID |
| `messages` | array | 是 | 按顺序排列的对话消息 |
| `messages[].role` | string | 是 | 常用值为 `system`、`user`、`assistant` |
| `messages[].content` | string 或 array | 是 | 消息内容。纯文本请求使用 string；多模态能力需以平台和模型实际支持为准 |
| `stream` | boolean | 否 | 是否使用流式响应，默认 `false`。需要流式输出时设置为 `true` |
| `temperature` | number | 否 | 控制采样随机性。常见范围为 `0` 到 `2`，实际范围以模型页面为准 |
| `top_p` | number | 否 | 核采样参数。常见范围为 `0` 到 `1`，实际范围以模型页面为准 |
| `n` | integer | 否 | 请求生成的候选回复数量。默认通常为 `1`；并非所有模型都支持大于 `1` |
| `max_tokens` | integer | 否 | 限制生成回复的最大 token 数。具体上限取决于模型 |
| `max_completion_tokens` | integer | 否 | 部分兼容接口用于限制最大补全 token 数；与 `max_tokens` 的支持情况因模型而异 |
| `stop` | string 或 array | 否 | 一个或多个停止生成标记；是否支持以所选模型为准 |
| `presence_penalty` | number | 否 | 调整模型引入新主题的倾向。常见范围为 `-2` 到 `2`，以模型支持为准 |
| `frequency_penalty` | number | 否 | 调整模型重复已出现词语的倾向。常见范围为 `-2` 到 `2`，以模型支持为准 |
| `seed` | integer | 否 | 尽可能提高结果可复现性的随机种子；不保证不同请求或模型版本完全一致 |
| `user` | string | 否 | 由调用方提供的终端用户标识；不要填写个人敏感信息 |
| `stream_options` | object | 否 | 流式响应选项，仅在所选模型及平台支持时使用 |
| `tools`、`tool_choice` | array / string / object | 否 | 工具调用定义与选择策略；仅在模型和应用同时支持工具调用时使用 |
| `response_format` | object | 否 | 指定输出格式的可选参数；支持范围以所选模型为准 |

不同模型对上下文长度、参数范围、工具调用和内容类型的支持可能不同。上表列出兼容接口的常见字段，不代表所有 FineOneAI 模型均支持每个字段。遇到参数不支持时，请先删除可选参数，只保留 `model`、`messages` 和认证信息进行测试。

## 使用 curl 调用

### 非流式请求

```bash theme={null}
curl "https://fineone-ai.fineres.com/v1/chat/completions" \
  -H "Authorization: Bearer $FINEONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "在平台模型页面查看准确模型 ID",
    "messages": [
      {"role": "user", "content": "请用一句话介绍 FineOneAI。"}
    ],
    "stream": false
  }'
```

### 流式请求

```bash theme={null}
curl -N "https://fineone-ai.fineres.com/v1/chat/completions" \
  -H "Authorization: Bearer $FINEONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "在平台模型页面查看准确模型 ID",
    "messages": [
      {"role": "user", "content": "请简要说明 API Key 的作用。"}
    ],
    "stream": true
  }'
```

流式响应通常以 Server-Sent Events 形式返回，每个数据块以 `data:` 开头；客户端应持续读取并拼接增量内容，收到 `data: [DONE]` 后结束读取。请使用支持 SSE 的 HTTP 客户端处理，不要把整个流当作单个 JSON 解析。

## 使用 Python 调用

```python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FINEONE_API_KEY"],
    base_url="https://fineone-ai.fineres.com/v1",
)

response = client.chat.completions.create(
    model="在平台模型页面查看准确模型 ID",
    messages=[
        {"role": "user", "content": "请用一句话介绍 FineOneAI。"}
    ],
)

print(response.choices[0].message.content)
```

安装依赖：

```bash theme={null}
pip install openai
```

`base_url` 填写 `https://fineone-ai.fineres.com/v1`，SDK 会自动补全 `/chat/completions`。如果直接使用 `urllib`、`requests` 等 HTTP 客户端，则应请求上方列出的完整 URL。

## 响应结构

非流式请求成功时，响应通常包含以下字段：

```json theme={null}
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1730000000,
  "model": "实际返回的模型 ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "模型返回的文本"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  }
}
```

常用回复内容位于 `choices[0].message.content`。`usage` 字段的具体可用性和统计方式以实际响应为准。

当 `stream` 为 `true` 时，响应由多个数据块组成，通常在 `choices[].delta` 中返回增量内容，而不是一次性返回 `choices[].message`。流式响应字段会随模型和平台实现而变化。

## 常见错误

| HTTP 状态 | 常见原因 | 检查方式 |
| - | - | - |
| `401` | API Key 缺失、错误、过期或已停用 | 检查 `Authorization: Bearer ` 前缀和密钥是否完整 |
| `403` | 账号或密钥没有模型权限 | 在模型页面确认账号和密钥可访问该模型 |
| `404` | URL 或模型 ID 不正确 | 使用完整 URL，确认没有重复拼接路径，并核对模型 ID |
| `400` | 请求体格式或参数不支持 | 先用最小请求体测试，再逐项增加可选参数 |
| `429` | 触发频率或额度限制 | 降低并发，检查账号额度和密钥额度，稍后重试 |
| `5xx` | 上游模型服务或平台暂时异常 | 记录请求时间和错误信息，稍后重试并查看调用记录 |

错误响应通常以 JSON 返回，并包含 `error.message` 等错误说明字段；具体状态码、字段和错误文本可能因校验阶段或上游服务而异。

反馈问题时，请提供请求时间、HTTP 状态码、模型 ID 和脱敏后的错误信息。不要提交 API Key、密码或完整业务数据。

## 使用限制

* 仅可调用 FineOneAI 控制台向当前账号开放的模型。
* DeepSeek、GLM、Kimi、Qwen 的具体模型版本和可用范围以平台模型页面为准。
* 平台已接入不代表与相关厂商存在官方合作、授权或背书关系。
* 注册账号不代表模型调用免费；价格、额度和使用规则以平台实际展示为准。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.