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

# Completions API

> 使用我們的 OpenAI 兼容聊天完成 API 與任何平台整合。

<Warning>
  **已棄用。** 此端點已棄用，將於 **2026-07-11 下架**。在此之前仍可使用。請改用 V1 路徑--完整的新舊路徑對照見[遷移指南](/zh-Hant/migrations/2026-06-outbound-api-v1)。
</Warning>

API 整合提供了一個 OpenAI 兼容的聊天完成端點，您可以用它來與您的 Pathors 專案進行互動。

## 基礎 URL

```
https://api.pathors.com
```

## 聊天完成

```bash theme={null}
POST /project/{projectId}/chat/completions
```

### 路徑參數

<ParamField path="projectId" type="string" required>
  您的專案 ID
</ParamField>

### 請求頭

<ParamField header="Authorization" type="string" required>
  使用您的 Project API Key（以 `sk_` 開頭）進行 Bearer 令牌認證。格式：`Bearer {your-api-key}`
</ParamField>

<ParamField header="X-Session-ID" type="string" optional>
  會話 ID，用於對話連續性。強烈建議使用此標頭傳遞會話 ID，而不是請求體中的
  session\_id 參數。
</ParamField>

### 請求體

<ParamField body="messages" type="array" required>
  對話中的訊息陣列。每條訊息都應該有一個 `role`（"system"、"user" 或
  "assistant"）和 `content`。
</ParamField>

<ParamField body="stream" type="boolean">
  是否流式傳輸回應。默認為 false。
</ParamField>

<ParamField body="session_id" type="string">
  (deprecated) 會話 ID，用於對話連續性。建議使用 X-Session-ID
  標頭代替。僅在不支持自訂標頭的環境中使用此參數。
</ParamField>

<ParamField body="tools" type="array">
  可供助手使用的外部工具定義陣列。每個工具應該有一個 `type`（目前僅支持 "function"）和一個包含 `name`、`description` 和 `parameters`（JSON Schema 格式）的 `function` 物件。
</ParamField>

請求範例：

```json theme={null}
{
  "messages": [
    {
      "role": "user",
      "content": "你好！"
    }
  ],
  "stream": false
}
```

帶工具的請求範例：

```json theme={null}
{
  "messages": [
    {
      "role": "user",
      "content": "舊金山的天氣怎麼樣？"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "獲取當前天氣資訊",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "城市名稱"
            }
          },
          "required": ["location"]
        }
      }
    }
  ]
}
```

### 回應頭

<ParamField header="X-Session-ID" type="string">
  對話的會話 ID。此頭部會在回應中返回，可用於後續請求。
</ParamField>

### 回應

<ResponseField name="id" type="string">
  完成的唯一標識符
</ResponseField>

<ResponseField name="object" type="string">
  物件類型（"chat.completion"）
</ResponseField>

<ResponseField name="created" type="number">
  完成創建時的 Unix 時間戳
</ResponseField>

<ResponseField name="model" type="string">
  用於完成的模型
</ResponseField>

<ResponseField name="choices" type="array">
  完成選項陣列
</ResponseField>

<ResponseField name="session_id" type="string">
  對話的會話 ID
</ResponseField>

<ResponseField name="choices[].message.tool_calls" type="array">
  助手進行的工具調用陣列（當提供並使用工具時）
</ResponseField>

<ResponseField name="choices[].finish_reason" type="string">
  完成終止的原因。正常完成時為 "stop"，調用工具時為 "tool\_calls"。
</ResponseField>

回應範例：

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "pathway-default",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我能幫你什麼忙？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": -1,
    "completion_tokens": -1,
    "total_tokens": -1
  },
  "session_id": "session-xyz789"
}
```

帶工具調用的回應範例：

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "pathway-default",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"location\": \"舊金山\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": -1,
    "completion_tokens": -1,
    "total_tokens": -1
  },
  "session_id": "session-xyz789"
}
```

### 流式回應

當 `stream` 設置為 `true` 時，回應將以伺服器發送事件（SSE）的形式流式傳輸。每個事件包含以下格式的回應塊：

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion.chunk",
  "created": 1677858242,
  "model": "pathway-default",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "你好"
      },
      "finish_reason": null
    }
  ],
  "session_id": "session-xyz789"
}
```

最後一個塊將有 `finish_reason: "stop"`，並跟隨 `data: [DONE]`。

### 錯誤回應

| 狀態碼 | 描述      |
| --- | ------- |
| 400 | 無效的請求體  |
| 401 | 無效的認證   |
| 500 | 內部伺服器錯誤 |

## 使用工具

當您在請求中提供工具時，助手可以在對話中調用它們。在收到帶有 `tool_calls` 的回應後，您應該：

1. 使用提供的參數執行請求的工具
2. 在後續請求中以 "tool" 角色訊息發送工具結果
3. 助手然後將使用工具結果來製定其最終回應

### 工具訊息格式

收到工具調用後，發送結果：

```json theme={null}
{
  "messages": [
    {"role": "user", "content": "天氣怎麼樣？"},
    {
      "role": "assistant",
      "content": "",
      "tool_calls": [
        {
          "id": "call_123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"location\": \"舊金山\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "content": "22°C，晴朗",
      "tool_call_id": "call_123",
      "name": "get_weather"
    }
  ],
  "session_id": "existing_session_id"
}
```

## 設置指南

1. 前往 **Project Settings > API Keys** 建立新的 API 金鑰
2. 立即複製金鑰（金鑰僅顯示一次）
3. 在請求中使用 `Authorization: Bearer {your-api-key}` 頭部
4. （可選）使用[會話 API](/api-reference/session/create-session)建立會話以維持對話連續性
5. （可選）定義並提供工具以擴展功能