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

# API 参考

> 基于 OpenAI 兼容格式的 RESTful API

## 鉴权

所有 API 请求需要在 Header 中携带 API Key：

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

可以在工作区设置 → API 密钥管理中创建和管理 API Key。

## Base URL

| 环境      | Base URL                   |
| ------- | -------------------------- |
| 云端 SaaS | `https://api.zgi.cn/v1`    |
| 私有化部署   | `http://YOUR_HOST:2678/v1` |

## 核心端点

* `POST /v1/chat/completions`：发送对话请求，支持知识库检索和流式输出

* `GET /v1/models`：获取可用模型列表

* `POST /v1/workflows/{workflow_id}/run`：触发指定工作流执行

* `POST /v1/knowledge-bases/{kb_id}/documents`：上传文档到知识库

* `POST /v1/knowledge-bases/{kb_id}/search`：查询知识库检索结果

## 对话请求示例

```bash theme={null}
curl -X POST https://api.zgi.cn/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zgi-default",
    "messages": [
      { "role": "system", "content": "你是一名合同审核助手" },
      { "role": "user", "content": "这份合同的付款条款是什么？" }
    ],
    "knowledge_base_id": "kb_xxxxxx",
    "stream": true,
    "temperature": 0.7
  }'
```

## 请求参数

| 参数                  | 类型      | 必填 | 说明        |
| ------------------- | ------- | -- | --------- |
| `model`             | string  | 必填 | 使用的模型 ID  |
| `messages`          | array   | 必填 | 对话消息数组    |
| `knowledge_base_id` | string  | 可选 | 关联的知识库 ID |
| `stream`            | boolean | 可选 | 是否启用流式输出  |
| `temperature`       | float   | 可选 | 采样温度（0-2） |

## SDK

```bash theme={null}
# Python
pip install zgi-sdk

# JavaScript / TypeScript
npm install @zgi/sdk
```

```python theme={null}
from zgi import ZGIClient

client = ZGIClient(api_key="YOUR_API_KEY")

# 查询知识库
result = client.knowledge.query(
    knowledge_base_id="kb_xxxxxx",
    question="这份合同的付款周期是多少天？"
)
print(result.answer)
print(result.citations)  # [{"source": "合同.pdf", "page": 4, "text": "..."}]

# 触发工作流
run = client.workflows.run(
    workflow_id="wf_xxxxxx",
    inputs={"document_url": "https://..."}
)
```