> ## 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.

# 快速入门

> 创建 API Key，选择模型，完成第一次 FineOneAI 调用

本文以一次文本对话请求为例，介绍 FineOneAI 的基础接入流程。

## 1. 登录平台

打开 [FineOneAI 控制台](https://fineone-ai.fineres.com/dashboard/overview)，按页面提供的方式注册或登录。

登录后，先确认账号具备可用额度。额度获取方式和模型使用规则以平台页面说明为准，注册账号不代表模型调用免费。

## 2. 创建 API Key

在控制台找到 API Key 或令牌管理入口，创建用于应用调用的密钥。

建议按应用命名，例如“业务系统测试”，便于后续识别调用来源。根据创建页面提供的选项设置有效期、额度和模型访问范围；首次测试时，确保所选模型在密钥允许的范围内。

创建后复制密钥，保存到应用的安全配置中。请勿将完整密钥提交到公开代码仓库或发送到聊天群。

账号额度与密钥额度分别生效，增加密钥额度不会增加账号额度。

## 3. 选择模型并确认地址

在平台模型页面选择一个当前账号可用、支持 Chat Completions 接口的模型，复制其准确模型 ID。

本文使用以下接入地址。如果平台提供了专门的 API 接入地址，请以平台展示的地址为准。

| 配置项 | 值 |
| - | - |
| 服务地址 | `https://fineone-ai.fineres.com` |
| Base URL | `https://fineone-ai.fineres.com/v1` |
| 文本对话接口 | `POST https://fineone-ai.fineres.com/v1/chat/completions` |
| 身份认证 | `Authorization: Bearer <你的 API Key>` |

不要把控制台页面地址 `/dashboard/overview` 填入 API 地址。应用若会自动补全 `/v1` 或接口路径，请按应用说明填写，避免路径重复。

## 4. 发起第一次请求

下面使用 Python 标准库发送请求，无需安装额外依赖。将代码保存为 `first_request.py`，运行后按提示在本机输入密钥和模型 ID。密钥输入时不会显示在终端中。

```python theme={null}
import getpass
import json
import urllib.error
import urllib.request

api_key = getpass.getpass("请输入 FineOneAI API Key：").strip()
model = input("请输入平台展示的模型 ID：").strip()
if not api_key or not model:
    raise SystemExit("API Key 和模型 ID 均不能为空。")

payload = {
    "model": model,
    "messages": [
        {"role": "user", "content": "你好，请用一句话介绍你能提供的帮助。"}
    ],
    "stream": False,
}

request = urllib.request.Request(
    "https://fineone-ai.fineres.com/v1/chat/completions",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)

try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.loads(response.read().decode("utf-8"))
    print(json.dumps(result, ensure_ascii=False, indent=2))
except urllib.error.HTTPError as error:
    print(f"请求失败，HTTP 状态码：{error.code}")
    print(error.read().decode("utf-8", errors="replace"))
except (urllib.error.URLError, TimeoutError) as error:
    print(f"连接失败或请求超时：{error}")
```

在终端运行：

```bash theme={null}
python first_request.py
```

如果你的电脑使用 `python3` 命令，请改为 `python3 first_request.py`。

请求成功后，返回结果的 `choices[0].message.content` 通常包含模型的文本回复。具体响应内容以模型实际返回为准。

## 5. 在应用中配置

如果你使用的应用支持自定义模型服务，可对照其接入说明填写以下内容：

| 应用中的字段 | 填写内容 |
| - | - |
| API Base URL / 接口地址 | 通常填写 `https://fineone-ai.fineres.com/v1`，是否包含 `/v1` 以应用说明为准 |
| API Key / 密钥 | 在 FineOneAI 创建的密钥 |
| Model / 模型名称 | 平台展示的准确模型 ID |

完成后执行应用自带的连接测试。应用能否使用流式输出、图片输入或工具调用，取决于应用和所选模型的共同支持情况。

## 6. 查看调用记录

返回控制台，查看调用日志或用量统计，确认请求是否成功，以及对应的模型、用量和费用信息。页面字段和可查看范围以平台实际配置为准。

## 调用失败时怎么检查

| 现象 | 优先检查 |
| - | - |
| 提示密钥无效或认证失败 | 密钥是否完整、是否过期或停用，认证头是否带有 `Bearer ` 前缀 |
| 提示额度不足 | 账号剩余额度与密钥剩余额度是否均满足要求 |
| 提示模型不可用或无权限 | 模型 ID 是否准确、密钥是否允许访问、账号是否具备模型权限 |
| 提示请求过于频繁 | 是否触发调用限制；降低并发并稍后重试 |
| 返回 404 或接口不存在 | 服务地址与接口路径是否正确，是否重复拼接 `/v1` |
| 请求超时或服务异常 | 查看错误信息和调用日志，稍后重试；避免连续重复提交 |

仍无法解决时，保留发生时间、模型 ID、HTTP 状态码和错误信息，提供给平台支持人员。反馈前请遮盖密钥及请求中的敏感内容。


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