96 lines
2.9 KiB
Plaintext
96 lines
2.9 KiB
Plaintext
---
|
||
title: HTTP API 调用
|
||
sidebarTitle: HTTP API
|
||
description: RESTful Chat Completions 接口说明
|
||
---
|
||
|
||
# HTTP API 调用
|
||
|
||
海宇数科网关提供与 OpenAI 兼容的 **RESTful HTTP API**，适用于任意编程语言、curl、API 网关或服务 mesh，无需安装专用 SDK。
|
||
|
||
## 基本信息
|
||
|
||
| 项目 | 值 |
|
||
| --- | --- |
|
||
| Base URL | `https://api.haiyushuke.com/v1` |
|
||
| 对话补全 | `POST /chat/completions` |
|
||
| Content-Type | `application/json` |
|
||
| 鉴权 | `Authorization: Bearer <API_KEY>` |
|
||
|
||
API Key 在控制台 **API Key** 创建；详见 [API Key 管理](/docs/guides/api_keys)。
|
||
|
||
## 请求示例
|
||
|
||
```bash
|
||
curl https://api.haiyushuke.com/v1/chat/completions \
|
||
-H "Authorization: Bearer YOUR_API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"model": "deepseek-chat",
|
||
"messages": [
|
||
{"role": "system", "content": "你是简洁的企业助手。"},
|
||
{"role": "user", "content": "什么是 Token？"}
|
||
],
|
||
"temperature": 0.7,
|
||
"max_tokens": 1024
|
||
}'
|
||
```
|
||
|
||
## 请求体常用字段
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `model` | string | **必填**。控制台模型广场中的 ID |
|
||
| `messages` | array | **必填**。`role`：`system` / `user` / `assistant` |
|
||
| `temperature` | number | 可选，采样随机性，常见 0–2 |
|
||
| `max_tokens` | integer | 可选，限制本次最大生成 token |
|
||
| `stream` | boolean | 可选，`true` 时返回 SSE，见 [流式调用](/docs/guides/streaming) |
|
||
|
||
部分模型支持更多参数（如 `top_p`、`stop` 等），与 OpenAI 兼容子集一致；不支持的字段可能被忽略或返回参数错误。
|
||
|
||
## 响应结构（非流式）
|
||
|
||
成功时 HTTP **200**，JSON 主体包含：
|
||
|
||
- `id`：请求标识
|
||
- `choices[].message.content`：模型回复文本
|
||
- `usage`：token 统计，用于对账，见 [核心概念](/docs/concepts/overview#token-与-usage)
|
||
|
||
```json
|
||
{
|
||
"choices": [
|
||
{
|
||
"message": { "role": "assistant", "content": "..." },
|
||
"finish_reason": "stop"
|
||
}
|
||
],
|
||
"usage": {
|
||
"prompt_tokens": 12,
|
||
"completion_tokens": 48,
|
||
"total_tokens": 60
|
||
}
|
||
}
|
||
```
|
||
|
||
## 错误与 HTTP 状态码
|
||
|
||
| 状态 | 常见原因 |
|
||
| --- | --- |
|
||
| 401 | Key 无效、过期、禁用或 Authorization 格式错误 |
|
||
| 402 | 账户余额不足（`INSUFFICIENT_BALANCE`） |
|
||
| 403 | Key 无该模型权限、IP 不在白名单等 |
|
||
| 429 | 限流，需退避重试 |
|
||
| 4xx/5xx | 参数错误、模型不存在或上游异常，见响应 body 中的 `message` / `code` |
|
||
|
||
更多排查见 [常见问题](/docs/faq)。
|
||
|
||
## 流式响应
|
||
|
||
设置 `"stream": true` 后，响应为 **SSE** 增量块，格式与 OpenAI 流式兼容。客户端须持续读取直至 `[DONE]`，并处理断线重试。
|
||
|
||
## 下一步
|
||
|
||
- [OpenAI SDK 兼容](/docs/guides/openai_compatible)
|
||
- [快速开始](/docs/getting-started)
|
||
- [工具接入概览](/docs/integrations/overview)（Cursor、Claude Code 等）
|