# API 參考文檔

## 端點

### GET /health

健康檢查

**響應**:
```json
{
  "status": "healthy",
  "model": "markbase-12b",
  "layers": 48,
  "vocabSize": 262144
}
```

### GET /v1/models

獲取可用模型列表

**響應**:
```json
{
  "data": [
    {
      "id": "markbase-12b",
      "object": "model",
      "owned_by": "markbase"
    }
  ]
}
```

### POST /v1/chat/completions

對話生成

**請求體**:
```json
{
  "messages": [
    {"role": "user", "content": "Hello"}
  ],
  "max_tokens": 100,
  "temperature": 0.7,
  "top_p": 0.95,
  "top_k": 40,
  "stream": false
}
```

**響應 (非流式)**:
```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "markbase-12b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 50,
    "total_tokens": 60
  }
}
```

**響應 (流式)**:
```
data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk",...,"choices":[{"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk",...,"choices":[{"delta":{"content":"Hello"},"finish_reason":null}]}

data: [DONE]
```

### POST /v1/completions

文本補全

**請求體**:
```json
{
  "prompt": "Hello, world!",
  "max_tokens": 100,
  "temperature": 0.7,
  "stream": false
}
```

## 參數說明

| 參數 | 類型 | 默認 | 說明 |
|------|------|------|------|
| `messages` | array | - | 對話消息列表 |
| `prompt` | string | - | 文本提示 |
| `max_tokens` | int | 100 | 最大生成 token 數 (1-4096) |
| `temperature` | float | 1.0 | 溫度 (0.0-2.0) |
| `top_p` | float | - | 核采樣閾值 (0.0-1.0) |
| `top_k` | int | - | Top-k 采樣 |
| `stream` | bool | false | 是否流式輸出 |

## 錯誤格式

```json
{
  "error": {
    "message": "Invalid request: prompt cannot be empty",
    "type": "invalid_request_error",
    "code": 400
  }
}
```

## 多模態格式

### 圖片

```json
{
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "描述這張圖片"},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,..."}}
      ]
    }
  ]
}
```

### 音訊

```json
{
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "轉錄這段音訊"},
        {"type": "audio_url", "audio_url": {"url": "data:audio/wav;base64,..."}}
      ]
    }
  ]
}
```