Chat Completions

POST /v1/chat/completions 的完整請求參數、訊息格式與回應結構。

Chat Completions

POST https://api.alphacurve.io/v1/chat/completions

這是 Inference 的核心端點。送出一組訊息，取得模型的回覆。請求與回應格式與 OpenAI Chat Completions API 相容。

請求參數

欄位	型別	說明
`model` *	string	模型 ID，例如 `openai/gpt-4o`、`anthropic/claude-sonnet-4-5`、`google/gemini-2.5-pro`。見 Models。
`messages` *	array	對話歷史。每個元素含 `role`（`system` \| `user` \| `assistant` \| `tool`）與 `content`。
`stream`	boolean	是否以 SSE 串流回傳。預設 `false`。
`stream_options`	object	串流選項，例如 `{"include_usage": true}` 讓最後一個 chunk 帶回 `usage`。
`temperature`	number	取樣溫度，0–2。數值越低越穩定。預設由上游模型決定。
`top_p`	number	Nucleus sampling。與 `temperature` 擇一使用。
`max_tokens`	integer	生成內容的最大 token 數。
`stop`	string \| array	遇到指定字串即停止生成，最多 4 組。
`n`	integer	生成幾組候選回覆。預設 `1`。
`presence_penalty`	number	−2.0 至 2.0，鼓勵談論新主題。
`frequency_penalty`	number	−2.0 至 2.0，降低重複。
`seed`	integer	盡力而為的決定性取樣，非保證。
`tools`	array	模型可呼叫的工具定義。見 Tools。
`tool_choice`	string \| object	`auto`、`none`、`required`，或指定某個工具。
`response_format`	object	`{"type": "json_object"}` 強制輸出合法 JSON。
`user`	string	你自訂的終端使用者識別碼，會記錄在用量報表中。

標示 * 者為必填。不支援的參數會被安全忽略，而不是回傳錯誤，這樣同一份程式碼可以跨模型執行。

訊息格式

content 可以是字串，也可以是 content part 陣列（用於 vision）：

{
  "messages": [
    { "role": "system", "content": "你是簡潔的助理。" },
    { "role": "user", "content": "台灣最高的山是哪一座？" },
    { "role": "assistant", "content": "玉山，海拔 3,952 公尺。" },
    { "role": "user", "content": "第二高呢？" }
  ]
}

Role	用途
`system`	系統指示。建議放在陣列最前面。
`user`	使用者輸入。
`assistant`	模型先前的回覆；帶 `tool_calls` 時代表模型要求呼叫工具。
`tool`	工具執行結果，必須帶 `tool_call_id`。

範例

curl

curl https://api.alphacurve.io/v1/chat/completions \
  -H "Authorization: Bearer $INFERENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-4-5",
    "messages": [
      { "role": "system", "content": "你是簡潔的助理。" },
      { "role": "user", "content": "用一句話說明什麼是路由。" }
    ],
    "temperature": 0.7,
    "max_tokens": 256
  }'

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.alphacurve.io/v1",
    api_key=os.environ["INFERENCE_API_KEY"],
)

resp = client.chat.completions.create(
    model="anthropic/claude-sonnet-4-5",
    messages=[
        {"role": "system", "content": "你是簡潔的助理。"},
        {"role": "user", "content": "用一句話說明什麼是路由。"},
    ],
    temperature=0.7,
    max_tokens=256,
)

print(resp.choices[0].message.content)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

Node / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.alphacurve.io/v1",
  apiKey: process.env.INFERENCE_API_KEY!,
});

const resp = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4-5",
  messages: [
    { role: "system", content: "你是簡潔的助理。" },
    { role: "user", content: "用一句話說明什麼是路由。" },
  ],
  temperature: 0.7,
  max_tokens: 256,
});

console.log(resp.choices[0].message.content);

回應格式

{
  "id": "chatcmpl-3f9a1c2b7d4e",
  "object": "chat.completion",
  "created": 1753776000,
  "model": "anthropic/claude-sonnet-4-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "路由是把每個請求送到最合適且目前可用的模型。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 21,
    "total_tokens": 49,
    "prompt_tokens_details": { "cached_tokens": 0 }
  }
}

欄位	說明
`id`	本次補全的識別碼，回報問題時請附上。
`model`	實際處理請求的模型 ID。
`choices[].finish_reason`	`stop`（自然結束）、`length`（達到 `max_tokens`）、`tool_calls`（要求呼叫工具）、`content_filter`（被上游過濾）。
`usage.prompt_tokens`	輸入 token 數。
`usage.completion_tokens`	輸出 token 數。
`usage.prompt_tokens_details.cached_tokens`	命中快取的輸入 token 數，以較低單價計費。

usage 就是我們的計費依據，詳見計費。

JSON 輸出

resp = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[
        {"role": "system", "content": "只輸出 JSON。"},
        {"role": "user", "content": "把「玉山 3952 公尺」轉成 {name, height_m}。"},
    ],
    response_format={"type": "json_object"},
)

import json
print(json.loads(resp.choices[0].message.content))