概述

OpenRoute AI 的请求和响应模式与 OpenAI Chat API 非常相似，只有一些小的差异。从高层次来看，OpenRoute AI 在模型和提供商之间标准化了模式，因此您只需要学习一种。

请求

完成请求格式

以下是作为 TypeScript 类型的请求模式。这将是您对 /api/v1/chat/completions 端点的 POST 请求的主体（有关示例，请参见上面的快速开始）。

有关参数的完整列表，请参见参数。

Request Schema

// Definitions of subtypes are below
type Request = {
  // Either "messages" or "prompt" is required
  messages?: Message[];
  prompt?: string;

  // If "model" is unspecified, uses the user's default
  model?: string; // See "Supported Models" section

  // Allows to force the model to produce specific output format.
  // See models page and note on this docs page for which models support it.
  response_format?: { type: 'json_object' };

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

  // See LLM Parameters (www.openroute.cn/docs/api-reference/parameters)
  max_tokens?: number; // Range: [1, context_length)
  temperature?: number; // Range: [0, 2]

  // Tool calling
  // Will be passed down as-is for providers implementing OpenAI's interface.
  // For providers with custom interfaces, we transform and map the properties.
  // Otherwise, we transform the tools into a YAML template. The model responds with an assistant message.
  // See models supporting tool calling: www.openroute.cn/models?supported_parameters=tools
  tools?: Tool[];
  tool_choice?: ToolChoice;

  // Advanced optional parameters
  seed?: number; // Integer only
  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; // Integer only
  min_p?: number; // Range: [0, 1]
  top_a?: number; // Range: [0, 1]

  // Reduce latency by providing the model with a predicted output
  // https://platform.openai.com/docs/guides/latency-optimization#use-predicted-outputs
  prediction?: { type: 'content'; content: string };

  // OpenRoute AI-only parameters
  // See "Prompt Transforms" section: www.openroute.cn/docs/transforms
  transforms?: string[];
  // See "Model Routing" section: www.openroute.cn/docs/model-routing
  models?: string[];
  route?: 'fallback';
  // See "Provider Routing" section: www.openroute.cn/docs/provider-routing
  provider?: ProviderPreferences;
  user?: string; // A stable identifier for your end-users. Used to help detect and prevent abuse.
};

// Subtypes:

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'
  | {
      type: 'function';
      function: {
        name: string;
      };
    };

response_format 参数确保您从 LLM 收到结构化响应。此参数仅由 OpenAI 模型、Nitro 模型和其他一些模型支持 - 请查看 openroute.cn/models 上模型页面的提供商以查看是否支持，并在您的提供商首选项中设置 require_parameters 为 true。请参见提供商路由

头部信息

OpenRoute AI 允许您指定一些可选的头部信息来标识您的应用程序，并使其在我们的网站上对用户可见。

HTTP-Referer: 在 openroute.cn 上标识您的应用程序
X-Title: 设置/修改您的应用程序标题

TypeScript

fetch('https://www.openroute.cn/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTE_API_KEY>',
    'HTTP-Referer': '<YOUR_SITE_URL>', // Optional. Site URL for rankings on openroute.cn.
    'X-Title': '<YOUR_SITE_NAME>', // Optional. Site title for rankings on openroute.cn.
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o',
    messages: [
      {
        role: 'user',
        content: 'What is the meaning of life?',
      },
    ],
  }),
});

模型路由

如果省略 model 参数，则使用用户或付款人的默认值。否则，请记住从支持的模型或API中为 model 选择一个值，并包含组织前缀。OpenRoute AI 将选择最便宜和最好的可用 GPU 来服务请求，如果收到 5xx 响应代码或您被限流，则会回退到其他提供商或 GPU。

流式传输

也支持服务器发送事件(SSE)，以启用_所有模型_的流式传输。只需在请求体中发送 stream: true。SSE 流偶尔会包含"注释"负载，您应该忽略它（如下所述）。

非标准参数

如果所选模型不支持请求参数（例如非 OpenAI 模型中的 logit_bias，或 OpenAI 的 top_k），则忽略该参数。其余参数将转发到底层模型 API。

助手预填充

OpenRoute AI 支持要求模型完成部分响应。这对于引导模型以某种方式响应很有用。

要使用此功能，只需在 messages 数组的末尾包含一个 role: "assistant" 的消息。

TypeScript

fetch('https://www.openroute.cn/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTE_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o',
    messages: [
      { role: 'user', content: 'What is the meaning of life?' },
      { role: 'assistant', content: "I'm not sure, but my best guess is" },
    ],
  }),
});

响应

完成响应格式

OpenRoute AI 在模型和提供商之间标准化模式，以符合OpenAI Chat API。

这意味着 choices 始终是一个数组，即使模型只返回一个完成。如果请求了流，每个选择将包含一个 delta 属性，否则包含一个 message 属性。这使得对所有模型使用相同的代码变得更容易。

以下是作为 TypeScript 类型的响应模式：

// 子类型定义如下
type Response = {
  id: string;
  // 根据您是否将 "stream" 设置为 "true" 以及
  // 您传入的是 "messages" 还是 "prompt"，您
  // 将获得不同的输出形状
  choices: (NonStreamingChoice | StreamingChoice | NonChatChoice)[];
  created: number; // Unix 时间戳
  model: string;
  object: 'chat.completion' | 'chat.completion.chunk';

  system_fingerprint?: string; // 仅在提供商支持时存在

  // 使用数据总是为非流式返回。
  // 流式传输时，您将在
  // 最后获得一个使用对象，伴随一个空的 choices 数组。
  usage?: ResponseUsage;
};

// 如果提供商返回使用情况，我们按原样传递。
// 否则，我们使用 GPT-4 分词器进行计数。

type ResponseUsage = {
  /** 包括图像和工具（如果有） */
  prompt_tokens: number;
  /** 生成的令牌 */
  completion_tokens: number;
  /** 上述两个字段的总和 */
  total_tokens: number;
};

// 子类型：
type NonChatChoice = {
  finish_reason: string | null;
  text: string;
  error?: ErrorResponse;
};

type NonStreamingChoice = {
  finish_reason: string | null;
  native_finish_reason: string | null;
  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 ErrorResponse = {
  code: number; // 参见"错误处理"部分
  message: string;
  metadata?: Record<string, unknown>; // 包含额外的错误信息，如提供商详情、原始错误消息等。
};

type ToolCall = {
  id: string;
  type: 'function';
  function: FunctionCall;
};

以下是一个示例：

{
  "id": "gen-xxxxxxxxxxxxxx",
  "choices": [
    {
      "finish_reason": "stop", // 标准化的 finish_reason
      "native_finish_reason": "stop", // 来自提供商的原始 finish_reason
      "message": {
        // 如果是流式传输则为 "delta"
        "role": "assistant",
        "content": "Hello there!"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 4,
    "total_tokens": 4
  },
  "model": "openai/gpt-3.5-turbo" // 也可能是 "anthropic/claude-2.1" 等，取决于最终使用的"模型"
}

完成原因

OpenRoute AI 将每个模型的 finish_reason 标准化为以下值之一：tool_calls、stop、length、content_filter、error。

某些模型和提供商可能有额外的完成原因。模型返回的原始 finish_reason 字符串可通过 native_finish_reason 属性获得。

查询成本和统计信息

完成 API 响应中返回的令牌计数不是通过模型的原生分词器计算的。相反，它使用标准化的、与模型无关的计数（通过 GPT4o 分词器实现）。这是因为某些提供商不能可靠地返回原生令牌计数。然而，这种行为变得越来越罕见，我们可能会在未来向响应对象添加原生令牌计数。

信用使用和模型定价基于原生令牌计数（不是 API 响应中返回的"标准化"令牌计数）。

要使用模型的原生分词器进行精确的令牌计算，您可以通过 /api/v1/generation 端点检索完整的生成信息。

您可以使用返回的 id 在请求完成后查询生成统计信息（包括令牌计数和成本）。这就是您如何获取_所有模型和请求_的成本和令牌，包括流式和非流式。

Query Generation Stats

const generation = await fetch(
  'https://www.openroute.cn/api/v1/generation?id=$GENERATION_ID',
  { headers },
);

const stats = await generation.json();

请参见生成 API 参考以了解完整的响应形状。

请注意，令牌计数也可在非流式完成的响应体的 usage 字段中获得。

请求

完成请求格式

以下是作为 TypeScript 类型的请求模式。这将是您对 /api/v1/chat/completions 端点的 POST 请求的主体（有关示例，请参见上面的快速开始）。

有关参数的完整列表，请参见参数。

Request Schema

// Definitions of subtypes are below
type Request = {
  // Either "messages" or "prompt" is required
  messages?: Message[];
  prompt?: string;

  // If "model" is unspecified, uses the user's default
  model?: string; // See "Supported Models" section

  // Allows to force the model to produce specific output format.
  // See models page and note on this docs page for which models support it.
  response_format?: { type: 'json_object' };

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

  // See LLM Parameters (www.openroute.cn/docs/api-reference/parameters)
  max_tokens?: number; // Range: [1, context_length)
  temperature?: number; // Range: [0, 2]

  // Tool calling
  // Will be passed down as-is for providers implementing OpenAI's interface.
  // For providers with custom interfaces, we transform and map the properties.
  // Otherwise, we transform the tools into a YAML template. The model responds with an assistant message.
  // See models supporting tool calling: www.openroute.cn/models?supported_parameters=tools
  tools?: Tool[];
  tool_choice?: ToolChoice;

  // Advanced optional parameters
  seed?: number; // Integer only
  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; // Integer only
  min_p?: number; // Range: [0, 1]
  top_a?: number; // Range: [0, 1]

  // Reduce latency by providing the model with a predicted output
  // https://platform.openai.com/docs/guides/latency-optimization#use-predicted-outputs
  prediction?: { type: 'content'; content: string };

  // OpenRoute AI-only parameters
  // See "Prompt Transforms" section: www.openroute.cn/docs/transforms
  transforms?: string[];
  // See "Model Routing" section: www.openroute.cn/docs/model-routing
  models?: string[];
  route?: 'fallback';
  // See "Provider Routing" section: www.openroute.cn/docs/provider-routing
  provider?: ProviderPreferences;
  user?: string; // A stable identifier for your end-users. Used to help detect and prevent abuse.
};

// Subtypes:

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'
  | {
      type: 'function';
      function: {
        name: string;
      };
    };

头部信息

OpenRoute AI 允许您指定一些可选的头部信息来标识您的应用程序，并使其在我们的网站上对用户可见。

HTTP-Referer: 在 openroute.cn 上标识您的应用程序
X-Title: 设置/修改您的应用程序标题

TypeScript

fetch('https://www.openroute.cn/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTE_API_KEY>',
    'HTTP-Referer': '<YOUR_SITE_URL>', // Optional. Site URL for rankings on openroute.cn.
    'X-Title': '<YOUR_SITE_NAME>', // Optional. Site title for rankings on openroute.cn.
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o',
    messages: [
      {
        role: 'user',
        content: 'What is the meaning of life?',
      },
    ],
  }),
});

模型路由

流式传输

非标准参数

如果所选模型不支持请求参数（例如非 OpenAI 模型中的 logit_bias，或 OpenAI 的 top_k），则忽略该参数。其余参数将转发到底层模型 API。

助手预填充

OpenRoute AI 支持要求模型完成部分响应。这对于引导模型以某种方式响应很有用。

要使用此功能，只需在 messages 数组的末尾包含一个 role: "assistant" 的消息。

TypeScript

fetch('https://www.openroute.cn/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <OPENROUTE_API_KEY>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o',
    messages: [
      { role: 'user', content: 'What is the meaning of life?' },
      { role: 'assistant', content: "I'm not sure, but my best guess is" },
    ],
  }),
});

响应

完成响应格式

OpenRoute AI 在模型和提供商之间标准化模式，以符合OpenAI Chat API。

以下是作为 TypeScript 类型的响应模式：

// 子类型定义如下
type Response = {
  id: string;
  // 根据您是否将 "stream" 设置为 "true" 以及
  // 您传入的是 "messages" 还是 "prompt"，您
  // 将获得不同的输出形状
  choices: (NonStreamingChoice | StreamingChoice | NonChatChoice)[];
  created: number; // Unix 时间戳
  model: string;
  object: 'chat.completion' | 'chat.completion.chunk';

  system_fingerprint?: string; // 仅在提供商支持时存在

  // 使用数据总是为非流式返回。
  // 流式传输时，您将在
  // 最后获得一个使用对象，伴随一个空的 choices 数组。
  usage?: ResponseUsage;
};

// 如果提供商返回使用情况，我们按原样传递。
// 否则，我们使用 GPT-4 分词器进行计数。

type ResponseUsage = {
  /** 包括图像和工具（如果有） */
  prompt_tokens: number;
  /** 生成的令牌 */
  completion_tokens: number;
  /** 上述两个字段的总和 */
  total_tokens: number;
};

// 子类型：
type NonChatChoice = {
  finish_reason: string | null;
  text: string;
  error?: ErrorResponse;
};

type NonStreamingChoice = {
  finish_reason: string | null;
  native_finish_reason: string | null;
  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 ErrorResponse = {
  code: number; // 参见"错误处理"部分
  message: string;
  metadata?: Record<string, unknown>; // 包含额外的错误信息，如提供商详情、原始错误消息等。
};

type ToolCall = {
  id: string;
  type: 'function';
  function: FunctionCall;
};

以下是一个示例：

{
  "id": "gen-xxxxxxxxxxxxxx",
  "choices": [
    {
      "finish_reason": "stop", // 标准化的 finish_reason
      "native_finish_reason": "stop", // 来自提供商的原始 finish_reason
      "message": {
        // 如果是流式传输则为 "delta"
        "role": "assistant",
        "content": "Hello there!"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 4,
    "total_tokens": 4
  },
  "model": "openai/gpt-3.5-turbo" // 也可能是 "anthropic/claude-2.1" 等，取决于最终使用的"模型"
}

完成原因

OpenRoute AI 将每个模型的 finish_reason 标准化为以下值之一：tool_calls、stop、length、content_filter、error。

某些模型和提供商可能有额外的完成原因。模型返回的原始 finish_reason 字符串可通过 native_finish_reason 属性获得。

查询成本和统计信息

信用使用和模型定价基于原生令牌计数（不是 API 响应中返回的"标准化"令牌计数）。

要使用模型的原生分词器进行精确的令牌计算，您可以通过 /api/v1/generation 端点检索完整的生成信息。

Query Generation Stats

const generation = await fetch(
  'https://www.openroute.cn/api/v1/generation?id=$GENERATION_ID',
  { headers },
);

const stats = await generation.json();

请参见生成 API 参考以了解完整的响应形状。

请注意，令牌计数也可在非流式完成的响应体的 usage 字段中获得。