跳轉到主要內容
ARouter 的請求和回應結構與 OpenAI Chat API 非常相似，有少量差異。ARouter 對所有模型和提供商的結構進行了統一規範，您只需學習一套即可。

​
OpenAPI 規範

完整的 ARouter API 使用 OpenAPI 規範進行了文件化： ARouter 目前發布 YAML 規範。您可以使用 Swagger UI 或 Postman 等工具來瀏覽 API 或生成客戶端程式庫。

​
Base URL

https://api.arouter.ai

​
認證

所有端點（/healthz 除外）都需要透過以下方式之一進行認證：
方式Header / 參數使用場景
Bearer TokenAuthorization: Bearer <key>OpenAI SDK、大多數客戶端
API Key HeaderX-Api-Key: <key>Anthropic SDK
查詢參數?key=<key>Gemini SDK
詳情請參閱認證指南。

​
請求

​
請求格式

以下是以 TypeScript 類型表示的請求結構。這將是您向 /v1/chat/completions 端點發起 POST 請求時的請求體。 完整參數列表請參閱參數參考文件。 
type Request = {
  // ARouter standardizes chat requests on "messages"
  messages?: Message[];

  // If "model" is unspecified, defaults to the tenant's configured default
  model?: string; // e.g. "openai/gpt-5.4" or "anthropic/claude-sonnet-4.6"

  // Force the model to produce specific output format.
  // See "Structured Outputs" guide for supported models.
  response_format?: ResponseFormat;

  stop?: string | string[];
  stream?: boolean; // Enable streaming

  // See Parameters reference
  max_tokens?: number; // Range: [1, context_length)
  temperature?: number; // Range: [0, 2]

  // Tool calling
  // Passed through to providers implementing OpenAI's interface.
  // For providers with custom interfaces, transformed accordingly.
  tools?: Tool[];
  tool_choice?: ToolChoice;
  parallel_tool_calls?: boolean; // Default: true

  // Advanced optional parameters
  seed?: number;
  top_p?: number; // Range: (0, 1]
  top_k?: number; // Range: [1, Infinity) — not available for OpenAI models
  frequency_penalty?: number; // Range: [-2, 2]
  presence_penalty?: number; // Range: [-2, 2]
  repetition_penalty?: number; // Range: (0, 2]
  logit_bias?: { [key: number]: number };
  top_logprobs?: number;
  min_p?: number; // Range: [0, 1]
  top_a?: number; // Range: [0, 1]

  // Reduce latency by providing a predicted output
  prediction?: { type: 'content'; content: string };

  // ARouter routing parameters
  models?: string[]; // Ordered candidate model list — see Model Routing guide
  route?: string;    // Routing mode used with models[]

  // A stable identifier for your end-users (for abuse detection)
  user?: string;
};
ARouter 的 OpenAI 相容聊天端點以 messages 為標準。如果您想發送提供商的原生請求體，請使用該提供商的原生端點或提供商代理。

​
訊息類型

type TextContent = {
  type: 'text';
  text: string;
};

type ImageContentPart = {
  type: 'image_url';
  image_url: {
    url: string; // URL or base64 encoded image data
    detail?: string; // Optional, defaults to "auto"
  };
};

type ContentPart = TextContent | ImageContentPart;

type Message =
  | {
      role: 'user' | 'assistant' | 'system';
      // ContentParts are only for the "user" role:
      content: string | ContentPart[];
      // If "name" is included, it will be prepended like this
      // for non-OpenAI models: `{name}: {content}`
      name?: string;
    }
  | {
      role: 'tool';
      content: string;
      tool_call_id: string;
      name?: string;
    };

​
工具類型

type FunctionDescription = {
  description?: string;
  name: string;
  parameters: object; // JSON Schema object
};

type Tool = {
  type: 'function';
  function: FunctionDescription;
};

type ToolChoice =
  | 'none'
  | 'auto'
  | 'required'
  | {
      type: 'function';
      function: {
        name: string;
      };
    };

​
結構化輸出

response_format 參數強制模型回傳結構化 JSON 回應。ARouter 支援兩種模式：
  • { type: 'json_object' }：基本 JSON 模式 — 模型回傳有效的 JSON
  • { type: 'json_schema', json_schema: { ... } }：嚴格模式 — 模型回傳符合您精確結構的 JSON
type ResponseFormat =
  | { type: 'json_object' }
  | {
      type: 'json_schema';
      json_schema: {
        name: string;
        strict?: boolean;
        schema: object; // JSON Schema object
      };
    };
詳細用法和範例請參閱結構化輸出。 使用 JSON 模式時，您仍應在系統或使用者訊息中指示模型以 JSON 格式回應。

​
可選請求 Header

ARouter 支援以下可選 header 來識別您的應用程式：
  • HTTP-Referer：您的應用程式 URL，用於在控制台中進行來源追蹤
  • X-Title：您的應用程式顯示名稱，用於 ARouter 分析
fetch('https://api.arouter.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer lr_live_xxxx',
    'HTTP-Referer': 'https://myapp.com', // Optional
    'X-Title': 'My AI App',             // Optional
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.4',
    messages: [{ role: 'user', content: 'Hello!' }],
  }),
});
詳情請參閱請求歸因。

​
模型路由

使用 provider/model 格式指定模型。ARouter 解析提供商前綴並路由到正確的上游。 如果省略 model 參數，將使用租戶設定的預設模型。完整路由邏輯請參閱模型路由指南，包括使用 models[] 和 route 的有序候選模型列表。

​
串流傳輸

設定 stream: true 可透過 Server-Sent Events 逐 Token 接收回應。SSE 串流除 data: 負載外還可包含註解行，客戶端應忽略這些註解。SSE 格式、用量區塊、取消和錯誤處理請參閱串流傳輸指南。

​
非標準參數

如果所選模型不支援某個請求參數（例如非 OpenAI 模型中的 logit_bias，或 OpenAI 的 top_k），該參數將被靜默忽略。其餘參數將轉發給上游模型 API。

​
助理預填充

ARouter 支援讓模型補全部分回應。在 messages 陣列末尾新增一條 role: "assistant" 的訊息： 
fetch('https://api.arouter.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer lr_live_xxxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-5.4',
    messages: [
      { role: 'user', content: 'What is the meaning of life?' },
      { role: 'assistant', content: "I'm not sure, but my best guess is" },
    ],
  }),
});

​
回應

​
回應格式

ARouter 對所有模型和提供商的結構進行了統一規範，以符合 OpenAI Chat API 標準。 choices 始終是一個陣列。如果請求了串流傳輸，每個 choice 包含 delta 屬性；否則包含 message 屬性。 
type Response = {
  id: string;
  choices: (NonStreamingChoice | StreamingChoice)[];
  created: number; // Unix timestamp
  model: string;   // The model that was actually used (e.g. "openai/gpt-5.4")
  object: 'chat.completion' | 'chat.completion.chunk';
  provider?: string; // The upstream provider that handled the request

  system_fingerprint?: string; // Only present if the provider supports it

  // Usage data is always returned for non-streaming.
  // When streaming, usage is returned exactly once in the final chunk,
  // before the [DONE] message, with an empty choices array.
  usage?: ResponseUsage;
};

​
Choice 類型

type NonStreamingChoice = {
  finish_reason: string | null; // Normalized finish reason
  native_finish_reason: string | null; // Raw finish reason from the provider
  message: {
    content: string | null;
    role: string;
    tool_calls?: ToolCall[];
  };
  error?: ErrorResponse;
};

type StreamingChoice = {
  finish_reason: string | null;
  native_finish_reason: string | null;
  delta: {
    content: string | null;
    role?: string;
    tool_calls?: ToolCall[];
  };
  error?: ErrorResponse;
};

type ToolCall = {
  id: string;
  type: 'function';
  function: {
    name: string;
    arguments: string; // JSON string
  };
};

type ErrorResponse = {
  code: number;
  message: string;
  metadata?: Record<string, unknown>;
};

​
用量

type ResponseUsage = {
  /** Including images and tools if any */
  prompt_tokens: number;
  /** The tokens generated */
  completion_tokens: number;
  /** Sum of the above two fields */
  total_tokens: number;

  /** Breakdown of prompt tokens */
  prompt_tokens_details?: {
    cached_tokens: number;        // Tokens read from cache (cache hit)
    cache_write_tokens?: number;  // Tokens written to cache
    audio_tokens?: number;        // Tokens used for input audio
  };

  /** Breakdown of completion tokens */
  completion_tokens_details?: {
    reasoning_tokens?: number;              // Tokens generated for reasoning
    accepted_prediction_tokens?: number;    // Accepted predicted output tokens
    rejected_prediction_tokens?: number;    // Rejected predicted output tokens
    audio_tokens?: number;                  // Tokens generated for audio output
    image_tokens?: number;                  // Tokens generated for image output
  };
};

​
回應範例

{
  "id": "chatcmpl-xxxxxxxxxxxxxx",
  "choices": [
    {
      "finish_reason": "stop",
      "native_finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Hello there!"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 4,
    "total_tokens": 14,
    "prompt_tokens_details": {
      "cached_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  },
  "model": "openai/gpt-5.4",
  "provider": "openai",
  "object": "chat.completion",
  "created": 1748000000
}

​
結束原因

ARouter 將每個模型的 finish_reason 統一規範為以下值之一：
值描述
stop模型自然完成
length達到 max_tokens 限制
tool_calls模型需要呼叫工具
content_filter內容審核觸發
error生成過程中發生錯誤
上游提供商的原始結束原因可透過 native_finish_reason 取得。

​
端點群組

OpenAI 相容

/v1/chat/completions, /v1/embeddings, /v1/models可與任何 OpenAI 相容 SDK 配合使用。支援 provider/model 路由。

Anthropic 原生

/v1/messages, /v1/messages/batches, /v1/messages/count_tokens與 Anthropic SDK 直接相容。

Gemini 原生

/v1beta/models/{model}:generateContent與 Google Gemini SDK 直接相容。

API Key 管理

/api/v1/keys建立、列出、更新和刪除 API key。

帳單

/api/v1/balance, /api/v1/transactions查詢帳戶餘額和交易歷史。

提供商代理

/{provider}/{path}將請求直接代理到任何受支援的提供商。

​
速率限制

速率限制按 API key 套用。預設限制可透過控制台或管理 API 按 key 自訂。
Header描述
X-RateLimit-Limit每個視窗期的最大請求數
X-RateLimit-Remaining剩餘請求數
X-RateLimit-Reset視窗期重置時間（Unix 時間戳）

​
錯誤回應

所有錯誤均遵循統一的 JSON 格式： 
{
  "error": {
    "message": "description of what went wrong",
    "type": "error_type"
  }
}
完整的錯誤代碼和重試策略請參閱錯誤處理指南。