# 快速开始

https://modelportal.ai/docs/quick-start?lang=zh

从注册到第一次调用分四步：注册、创建 API 密钥、发送请求、按需选择供应商。下面的示例可以直接复制，把 `YOUR_API_KEY` 换成你的密钥、`MODEL_ID` 换成模型 ID 即可。

## 1. 注册

用邮箱注册并点击验证邮件里的链接。创建密钥和充值都要求先验证邮箱，验证链接 24 小时内有效、只能用一次。实例开启了新用户试用额度时，验证邮箱后会自动发放一笔赠送额度，发放后在控制台的余额里就能看到；没有试用额度时，先在「充值」页充值。

## 2. 创建 API 密钥

进入控制台「密钥」页，填写名称即可创建。完整密钥形如 `mp-xxxxxxxx.xxxx`，只在创建时显示一次，请马上保存；之后只能看到末 4 位，遗失了就撤销再新建，详见[密钥管理](/docs/api-keys)。

密钥只在服务端使用：放进服务端的环境变量或密钥管理系统，不要写进浏览器页面、移动应用安装包或公开仓库。

## 3. 发送第一次请求

在[模型目录](/models)找到要用的模型，详情页里的「模型 ID」就是请求里 `model` 字段的值。下面三种写法发出的是同一个请求：

```bash
curl https://modelportal.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "messages": [{"role": "user", "content": "你好"}]}'
```

```python
from openai import OpenAI

client = OpenAI(base_url="https://modelportal.ai/v1", api_key="YOUR_API_KEY")
reply = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "你好"}],
)
print(reply.choices[0].message.content)
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({ baseURL: "https://modelportal.ai/v1", apiKey: "YOUR_API_KEY" });
const reply = await client.chat.completions.create({
  model: "MODEL_ID",
  messages: [{ role: "user", content: "你好" }],
});
console.log(reply.choices[0].message.content);
```

Python 先 `pip install openai`，TypeScript 先 `npm install openai`。返回里的 `choices[0].message.content` 就是模型的回答，这次调用的费用可以在控制台「账单」页看到。

平台提供三种兼容接口，地址都在本站域名下：

| 协议 | 基础地址 | 认证方式 |
| --- | --- | --- |
| OpenAI 兼容 | `https://modelportal.ai/v1` | `Authorization: Bearer <密钥>` |
| Anthropic 兼容 | `https://modelportal.ai`（不带 `/v1`） | `x-api-key: <密钥>` 或 Bearer |
| Gemini 兼容 | `https://modelportal.ai/v1beta`（Google GenAI SDK 填 `https://modelportal.ai`） | `x-goog-api-key: <密钥>`、查询参数 `key` 或 Bearer |

## 4. 选择供应商

同一个模型通常有几家供应商的报价。不做任何设置时，平台按比价价格选最便宜的合格报价，这次请求就锁定在它上面，失败直接返回错误，不会换到别家。想优先用某家供应商，在请求体里加 `provider` 对象：

```bash
curl https://modelportal.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "messages": [{"role": "user", "content": "你好"}], "provider": {"order": ["PROVIDER_ID"]}}'
```

`PROVIDER_ID` 换成模型详情页报价列表里的供应商标识。没有任何报价满足条件时，返回 HTTP 422，错误码 `no_eligible_endpoint`，错误信息会说明原因。`provider` 的全部字段见[供应商选择](/docs/provider-routing)。

## 需要注意的默认行为

- 流式输出：请求里加 `"stream": true`，OpenAI 格式以 `data: [DONE]` 结束，见[流式输出](/docs/streaming)。
- 没填 `max_tokens`（或 `max_completion_tokens`）时，平台按模型的输出上限和你的可用余额补一个值；Anthropic 格式的 `max_tokens` 必填。
- `GET /v1/models` 只列出当前密钥可以调用的模型。
- 余额不足时返回 HTTP 402 `insufficient_balance`，充值后即可继续调用。更多错误见[常见错误](/docs/errors)。

## 常见问题

### 请求里的 model 应该填什么？

填模型目录详情页上的「模型 ID」。GET /v1/models 也会列出当前密钥可以调用的全部模型 ID。

### 必须先验证邮箱吗？

创建 API 密钥、充值和使用兑换码都需要先验证邮箱。浏览模型目录和价格不需要。

### 支持哪些 SDK？

OpenAI 官方 SDK 把 base_url 设为 https://modelportal.ai/v1 即可；Anthropic SDK 直接设为 https://modelportal.ai，不带 /v1；Google GenAI SDK 把 base_url 设为 https://modelportal.ai，不带 /v1beta，Key 照常填。

### 没填 max_tokens 会怎样？

OpenAI 与 Gemini 格式由平台补一个值：取模型的最大输出（模型没设时为 4096），再按你的可用余额收紧到付得起的数。Anthropic 格式的 max_tokens 是必填项，缺少会直接报错。