# Qwen 3.8 27B 文本 API：快速开始

Base URL：`https://text-api.chatpig.space`（OpenAI SDK 的 `base_url` 填 `https://text-api.chatpig.space/v1`）。
模型名称：`qwen3.8-27b-uncensored`（16,384 上下文，支持普通 JSON 与 `stream: true` SSE 流式输出）。

## 1. 鉴权配置

所有接口调用均通过请求头携带 `Authorization: Bearer <API_KEY>`（仅 `/docs`、`/quickstart.md`、`/health` 免鉴权）。

```bash
export TEXT_API_KEY='你的 API Key'
```

---

## 2. 对话生成接口（OpenAI 兼容）

### 2.1 普通 JSON 请求（POST /v1/chat/completions）

```bash
curl https://text-api.chatpig.space/v1/chat/completions \
  -H "Authorization: Bearer $TEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-27b-uncensored",
    "messages": [
      {"role": "system", "content": "你是一个简洁直接的助手。"},
      {"role": "user", "content": "计算 37 × 19，并用一句中文回答。"}
    ],
    "max_tokens": 512,
    "temperature": 0.7,
    "stream": false
  }'
```

### 2.2 SSE 流式输出（stream: true）

```bash
curl -N https://text-api.chatpig.space/v1/chat/completions \
  -H "Authorization: Bearer $TEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-27b-uncensored",
    "messages": [
      {"role": "user", "content": "用中文介绍一下你自己。"}
    ],
    "max_tokens": 512,
    "temperature": 0.7,
    "stream": true
  }'
```

### 2.3 使用官方 OpenAI Python SDK

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://text-api.chatpig.space/v1",
    api_key="你的 API Key",
)

stream = client.chat.completions.create(
    model="qwen3.8-27b-uncensored",
    messages=[{"role": "user", "content": "用中文介绍一下你自己。"}],
    max_tokens=512,
    temperature=0.7,
    stream=True,
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

### 2.4 查询模型列表（GET /v1/models）

```bash
curl https://text-api.chatpig.space/v1/models \
  -H "Authorization: Bearer $TEXT_API_KEY"
```

---

## 3. GPU 控制接口（状态 / 启动 / 续期 / 释放）

| 功能 | 方法与路径 | 请求体示例 / 说明 |
|---|---|---|
| **查看 GPU 状态** | `GET /gpu/status` | 返回 `state`、`ready`、剩余租约/闲置分钟数 |
| **启动 A100（租约+闲置保护）** | `POST /gpu/start` | `{"keep_online_minutes": 120, "idle_timeout_minutes": 30, "keep_forever": false, "confirm_gpu_charge": true}` |
| **启动 A100（常驻不自动关机）** | `POST /gpu/start` | `{"keep_forever": true, "confirm_gpu_charge": true}` |
| **延长 GPU 租约** | `POST /gpu/extend` | `{"extra_minutes": 60}` |
| **立即释放 GPU** | `POST /gpu/stop` | 释放云端 A100 会话并下线网关路由 |

### 3.1 查看 GPU 状态（GET /gpu/status）

```bash
curl https://text-api.chatpig.space/gpu/status \
  -H "Authorization: Bearer $TEXT_API_KEY"
```

返回字段说明：
- `state`：`offline`（已关机）、`starting`（分配 A100 中）、`warming`（下载/加载模型预热中）、`ready`（已就绪可推理）、`busy`（推理中）、`recovering`（恢复连接中）、`stopping`（释放中）
- `ready`：`true` 表示模型已预热完毕，可立即调用 `/v1/chat/completions`
- `lease_remaining_minutes` / `idle_remaining_minutes`：当前剩余租约分钟数与闲置自动关机倒计时（常驻模式下为 `null`）

### 3.2 启动 A100（POST /gpu/start）

```bash
# 方式 1：租约 + 闲置自动关机保护（默认保持 120 分钟，连续 30 分钟无对话自动关机）
curl -X POST https://text-api.chatpig.space/gpu/start \
  -H "Authorization: Bearer $TEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keep_online_minutes": 120, "idle_timeout_minutes": 30, "keep_forever": false, "confirm_gpu_charge": true}'

# 方式 2：常驻不自动关机（直到显式调用 /gpu/stop）
curl -X POST https://text-api.chatpig.space/gpu/start \
  -H "Authorization: Bearer $TEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keep_forever": true, "confirm_gpu_charge": true}'
```

### 3.3 延长 GPU 租约（POST /gpu/extend）

```bash
curl -X POST https://text-api.chatpig.space/gpu/extend \
  -H "Authorization: Bearer $TEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"extra_minutes": 60}'
```

### 3.4 立即释放 GPU（POST /gpu/stop）

```bash
curl -X POST https://text-api.chatpig.space/gpu/stop \
  -H "Authorization: Bearer $TEXT_API_KEY"
```