POST
/
api
/
project
/
{projectId}
/
integration
/
api
/
chat
/
completions
Completions API
curl --request POST \
  --url https://app.pathors.com/api/project/{projectId}/integration/api/chat/completions \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messages": [
    {}
  ],
  "stream": true,
  "session_id": "<string>",
  "tools": [
    {}
  ]
}'
{
  "id": "<string>",
  "object": "<string>",
  "created": 123,
  "model": "<string>",
  "choices": [
    {}
  ],
  "session_id": "<string>",
  "choices[].message.tool_calls": [
    {}
  ],
  "choices[].finish_reason": "<string>"
}
API 整合提供了一個 OpenAI 兼容的聊天完成端點，您可以用它來與您的 Pathors 專案進行互動。

​
聊天完成

​
路徑參數

​
projectId
string
required
您的專案 ID

​
請求頭

​
Authorization
string
required
使用您的 API 金鑰進行 Bearer 令牌認證
​
X-Session-ID
string
會話 ID，用於對話連續性。強烈建議使用此標頭傳遞會話 ID，而不是請求體中的 session_id 參數。

​
請求體

​
messages
array
required
對話中的訊息陣列。每條訊息都應該有一個 role（“system”、“user” 或 “assistant”）和 content。
​
stream
boolean
是否流式傳輸回應。默認為 false。
​
session_id
string
(deprecated) 會話 ID，用於對話連續性。建議使用 X-Session-ID 標頭代替。僅在不支持自訂標頭的環境中使用此參數。
​
tools
array
可供助手使用的外部工具定義陣列。每個工具應該有一個 type（目前僅支持 “function”）和一個包含 name、description 和 parameters（JSON Schema 格式）的 function 物件。
請求範例： 
{
  "messages": [
    {
      "role": "user",
      "content": "你好！"
    }
  ],
  "stream": false
}
帶工具的請求範例： 
{
  "messages": [
    {
      "role": "user",
      "content": "舊金山的天氣怎麼樣？"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "獲取當前天氣資訊",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "城市名稱"
            }
          },
          "required": ["location"]
        }
      }
    }
  ]
}

​
回應頭

​
X-Session-ID
string
對話的會話 ID。此頭部會在回應中返回，可用於後續請求。

​
回應

​
id
string
完成的唯一標識符
​
object
string
物件類型（“chat.completion”）
​
created
number
完成創建時的 Unix 時間戳
​
model
string
用於完成的模型
​
choices
array
完成選項陣列
​
session_id
string
對話的會話 ID
​
choices[].message.tool_calls
array
助手進行的工具調用陣列（當提供並使用工具時）
​
choices[].finish_reason
string
完成終止的原因。正常完成時為 “stop”，調用工具時為 “tool_calls”。
回應範例： 
{
  "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"
}
帶工具調用的回應範例： 
{
  "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）的形式流式傳輸。每個事件包含以下格式的回應塊： 
{
  "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. 助手然後將使用工具結果來製定其最終回應

​
工具訊息格式

收到工具調用後，發送結果： 
{
  "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. 在您的 Pathors 專案設置中啟用 API 整合
  2. 在您專案的整合設置中生成 API 金鑰
  3. 在您的請求中使用 API 金鑰作為 Authorization 頭部
  4. （可選）使用會話 API建立會話以維持對話連續性
  5. （可選）定義並提供工具以擴展功能