---
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 等）