OpenRouter 文档

未来将会给我们带来数百种语言模型和每种模型的数十个提供者。你将如何选择最佳的呢？

优先考虑价格还是性能。OpenRouter 会在数十家供应商中寻找最低的价格和最佳的延迟/吞吐量，并让您选择如何对它们进行优先排序。

标准化的 API。在切换模型或供应商时无需更改您的代码。您甚至可以让用户自行选择和支付。

最好的模型将被最多地使用。评估存在缺陷。相反，通过它们的使用频率以及不久后将把用途来比较模型。在 Playground 中同时与多个模型进行交流。

快速入门

typescriptpythonshell

typescript

fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${OPENROUTER_API_KEY}`,
    "HTTP-Referer": `${YOUR_SITE_URL}`, // 可选项，用于将您的应用程序列入 openrouter.ai 排行榜。
    "X-Title": `${YOUR_SITE_NAME}`, // 可选项。显示在 openrouter.ai 网站的排名中。
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "openai/gpt-3.5-turbo",
    "messages": [
      {"role": "user", "content": "生命的意义是什么？"},
    ],
  })
});

python

import requests
import json

response = requests.post(
  url="https://openrouter.ai/api/v1/chat/completions",
  headers={
    "Authorization": f"Bearer {OPENROUTER_API_KEY}",
    "HTTP-Referer": f"{YOUR_SITE_URL}", # 可选项，用于将您的应用程序列入 openrouter.ai 排行榜。
    "X-Title": f"{YOUR_APP_NAME}", # 可选项。显示在 openrouter.ai 网站的排名中。
  },
  data=json.dumps({
    "model": "openai/gpt-3.5-turbo", # Optional
    "messages": [
      {"role": "user", "content": "生命的意义是什么？"}
    ]
  })
)

shell

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
  "model": "openai/gpt-3.5-turbo",
  "messages": [
    {"role": "user", "content": "生命的意义是什么？"}
  ]
}'

您也可以使用OpenAI的客户端API与OpenRouter一起使用。

typescriptpython

typescript

import OpenAI from "openai"

const openai = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: $OPENROUTER_API_KEY,
  defaultHeaders: {
    "HTTP-Referer": $YOUR_SITE_URL,
    "X-Title": $YOUR_SITE_NAME,
  },
  // dangerouslyAllowBrowser: true,
})
async function main() {
  const completion = await openai.chat.completions.create({
    model: "openai/gpt-3.5-turbo",
    messages: [
      { role: "user", content: "说这是一次测试" }
    ],
  })

  console.log(completion.choices[0].message)
}
main()

python

from openai import OpenAI
from os import getenv

# gets API Key from environment variable OPENAI_API_KEY
client = OpenAI(
  base_url="https://openrouter.ai/api/v1",
  api_key=getenv("OPENROUTER_API_KEY"),
)

completion = client.chat.completions.create(
  extra_headers={
    "HTTP-Referer": $YOUR_SITE_URL,
    "X-Title": $YOUR_APP_NAME,
  },
  model="openai/gpt-3.5-turbo",
  messages=[
    {
      "role": "user",
      "content": "说这是一次测试",
    },
  ],
)
print(completion.choices[0].message.content)

支持的模型

模型使用可以由用户、开发者或两者支付，并且可能会在可用性上发生变化。您还可以通过 API 获取模型、价格和限制。

令牌计数是近似值。OpenRouter 不存储提示或完成信息。

如果您想直接向 OpenRouter 添加开源模型，请访问我们的 Github。

文字模型

媒体模型

注意：不同的模型以不同的方式对文本进行标记化。一些模型将文本分成多个字符的块（GPT、Claude、Llama等），而其他模型则按字符进行标记化（PaLM）。这意味着标记的数量可能会因模型而异。

提供商路由

OpenRouter将每个请求路由到您偏好的最佳可用模型提供者。您可以使用请求主体中的 provider 对象进行自定义。以下是可用选项：

自定义提供商选择

您可以使用 order 字段设置 OpenRouter 将用于您的请求的提供商。路由器将过滤此列表，仅包括适用于您使用的型号的提供商，然后逐个尝试，如果没有可用的提供商，则失败。如果您不设置此字段，路由器将使用模型页面上显示的默认顺序。

typescript

fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${OPENROUTER_API_KEY}`,
    "HTTP-Referer": `${YOUR_SITE_URL}`,
    "X-Title": `${YOUR_SITE_NAME}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "mistralai/mixtral-8x7b-instruct",
    "messages": [
      {"role": "user", "content": "Hello"},
    ],
    "provider": {
      "order": [
        "Azure",
        "Together"
      ]
    },
  })
});

必需参数（测试版）

默认情况下，不支持特定LLM参数的提供商将忽略它们。但您可以更改此设置，仅筛选出支持您请求中的参数的提供商。

例如，只使用支持 JSON 格式的提供商：

typescript

fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${OPENROUTER_API_KEY}`,
    "HTTP-Referer": `${YOUR_SITE_URL}`, 
    "X-Title": `${YOUR_SITE_NAME}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "mistralai/mixtral-8x7b-instruct",
    "messages": [
      {"role": "user", "content": "Hello"},
    ],
    "provider": {
      "require_parameters": true
    },
    "response_format": {
      "type": "json_object"
    },
  })
});

数据隐私

一些模型提供商可能会记录提示信息，因此我们在模型页面上使用数据政策标签显示它们。这并不是第三方数据政策的权威来源，但代表了我们的最佳了解。

OpenRouter 的数据政策在您的账户页面上进行管理。您可以在那里禁用日志记录，以禁用存储日志用于训练等目的的第三方模型提供商。或者，您可以根据每个请求跳过它们：

typescript

fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${OPENROUTER_API_KEY}`,
    "HTTP-Referer": `${YOUR_SITE_URL}`,
    "X-Title": `${YOUR_SITE_NAME}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "mistralai/mixtral-8x7b-instruct",
    "messages": [
      {"role": "user", "content": "Hello"},
    ],
    "provider": {
      "data_collection": "deny"
    },
  })
});

禁用提供者会导致路由器跳过它并继续选择下一个最佳提供者。

禁用回退

为了确保您的请求只由顶级（成本最低）提供商提供服务，您可以禁用回退：

typescript

fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${OPENROUTER_API_KEY}`,
    "HTTP-Referer": `${YOUR_SITE_URL}`,
    "X-Title": `${YOUR_SITE_NAME}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "mistralai/mixtral-8x7b-instruct",
    "messages": [
      {"role": "user", "content": "Hello"},
    ],
    "provider": {
      "allow_fallbacks": false
    },
  })
});

有关所有选项的完整列表，请参阅此 JSON 模式：

json

{
  "$ref": "#/definitions/ProviderPreferences",
  "definitions": {
    "ProviderPreferences": {
      "type": "object",
      "properties": {
        "allow_fallbacks": {
          "type": "boolean",
          "description": "Whether to allow backup providers to serve requests
- true: (default) when the primary provider is unavailable, use the next best provider.
- false: use only the primary provider, and return the upstream error if it's unavailable.
",
          "default": true
        },
        "require_parameters": {
          "type": "boolean",
          "description": "Whether to filter providers to only those that support the parameters you've provided. If this setting is omitted or set to false, then providers will receive only the parameters they support, and ignore the rest.",
          "default": false
        },
        "data_collection": {
          "type": "string",
          "enum": [
            "deny",
            "allow"
          ],
          "description": "Data collection setting. If no available model provider meets the requirement, your request will return an error.
- allow: (default) allow providers which store user data non-transiently and may train on it
- deny: use only providers which do not collect user data.
",
          "default": "allow"
        },
        "order": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "OpenAI",
              "Anthropic",
              "HuggingFace",
              "Google",
              "Mancer",
              "Mancer 2",
              "Together",
              "DeepInfra",
              "Azure",
              "Modal",
              "AnyScale",
              "Replicate",
              "Perplexity",
              "Recursal",
              "Fireworks",
              "Mistral",
              "Groq",
              "Cohere",
              "Lepton",
              "OctoAI"
            ]
          },
          "description": "An ordered list of provider names. The router will attempt to use the first provider in the subset of this list that supports your requested model, and fall back to the next if it is unavailable. If no providers are available, the request will fail with an error message."
        }
      },
      "additionalProperties": false
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

模型路由

多模型路由正在开发中👀

自动路由器，这是一个特殊的模型ID，您可以使用它来根据应用于您的提示的启发式选择所选高质量模型。
该 models 数组允许您在主要模型的提供者不可用、受到速率限制或因所有提供者要求内容审核而拒绝回复时，自动尝试其他模型。

json

{
  "models": ["anthropic/claude-2.1", "gryphe/mythomax-l2-13b"],
  "route": "fallback",
  ... // Other params
}

如果您选择的模型返回错误，OpenRouter 将尝试使用备用模型。如果备用模型不可用或返回错误，OpenRouter 将返回该错误。

默认情况下，任何错误都可以触发使用备用模型，包括上下文长度验证错误、过滤模型的审查标志、速率限制和停机时间。

请求的定价是使用的模型进行的，该模型将在响应主体的 model 属性中返回。

如果未指定回退模型但仍包括 route: "fallback" ，OpenRouter 将尝试使用最合适的开源模型，价格低于主要模型（或非常接近）。

OAuth PKCE

用户可以使用 Proof Key for Code Exchange（PKCE）一键连接到 OpenRouter。这里有一个例子，以及一个逐步说明：

将您的用户发送到 https://openrouter.ai/auth?callback_url=YOUR_SITE_URL
- 您可以选择包含一个 code_challenge （最多256位的随机密码）以提高安全性。
- 为了最大限度的安全性，我们建议将 code_challenge_method 设置为 S256 ，然后将 code_challenge 设置为 code_verifier 的 sha256 哈希的 base64 编码，您将在第2步中提交。有关更多信息，请参阅 Auth0 的文档。
一旦登录，他们将被重定向回您的网站，并在URL中带有一个 code 。进行API调用（可以是前端或后端），以交换代码获取用户可控的API密钥。这就是PKCE的全部内容！
- 寻找 code 查询参数，例如 ?code=... 。
typescript
```
fetch("https://openrouter.ai/api/v1/auth/keys", {
  method: 'POST',
  body: JSON.stringify({
    code: $CODE_FROM_QUERY_PARAM,
    code_verifier: $CODE_VERIFIER // 只有在步骤1中发送了code_challenge时才需要
  })
});
```

一个新的 API 密钥将在 “key” 下的结果中。请安全存储并进行 OpenAI 风格的请求（支持流式传输）。

typescript

fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${OPENROUTER_API_KEY}`,
    "HTTP-Referer": `${YOUR_SITE_URL}`,
    "X-Title": `${YOUR_SITE_NAME}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "anthropic/claude-2",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"},
    ],
  })
});

您可以使用 JavaScript 或任何服务器端框架，比如 Streamlit。链接的示例展示了多个模型和文件问答。

API Keys

用户或开发人员可以使用普通的 API 密钥来支付模型成本。这使您可以直接使用 OpenRouter 的 curl 或 OpenAI SDK。只需创建一个 API 密钥，设置 api_base ，并可选择设置一个引荐头部，以便让您的应用在 OpenRouter 上被其他人发现。

注意：OpenRouter 上的 API 密钥比直接用于模型 API 的密钥更强大。它们允许用户为应用程序设置信用额度，并且可以在 OAuth 流程中使用。

示例代码:

typescriptpythonshell

typescript

import OpenAI from "openai"

const openai = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: $OPENROUTER_API_KEY,
  defaultHeaders: {
    "HTTP-Referer": $YOUR_SITE_URL,
    "X-Title": $YOUR_SITE_NAME,
  },
  // dangerouslyAllowBrowser: true,
})
async function main() {
  const completion = await openai.chat.completions.create({
    model: "openai/gpt-3.5-turbo",
    messages: [
      { role: "user", content: "Say this is a test" }
    ],
  })

  console.log(completion.choices[0].message)
}
main()

python

import openai

openai.api_base = "https://openrouter.ai/api/v1"
openai.api_key = $OPENROUTER_API_KEY

response = openai.ChatCompletion.create(
  model="openai/gpt-3.5-turbo",
  messages=[...],
  headers={
    "HTTP-Referer": $YOUR_SITE_URL,
    "X-Title": $YOUR_APP_NAME,
  },
)

reply = response.choices[0].message

shell

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
  "model": "openai/gpt-4-32k",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ]
}'

要使用Python进行流式处理，请参考 OpenAI 的这个示例。

请求

OpenRouter 的请求和响应模式与 OpenAI Chat API 非常相似，只有一些细微的差异。在高层次上，OpenRouter 会对模型和提供者进行模式规范化，因此您只需要学习一个。

请求主体

这是一个 TypeScript 类型的请求模式。这将是您发送到 /api/v1/chat/completions 端点的 POST 请求的主体（请参阅上面的快速入门示例）。

typescript

// 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.
  // Only supported by OpenAI models, Nitro models, and some others - check the
  // providers on the model page on openrouter.ai/models to see if it's supported,
  // and set `require_parameters` to true in your Provider Preferences. See
  // openrouter.ai/docs#provider-routing
  response_format?: { type: 'json_object' };

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

  // See LLM Parameters (openrouter.ai/docs#parameters)
  max_tokens?: number; // Range: [1, context_length)
  temperature?: number; // Range: [0, 2]
  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]
  seed?: number; // OpenAI only

  // Function-calling
  // Only natively suported by OpenAI models. For others, we submit
  // a YAML-formatted string with these tools at the end of the prompt.
  tools?: Tool[];
  tool_choice?: ToolChoice;

  // Additional optional parameters
  logit_bias?: { [key: number]: number };

  // OpenRouter-only parameters
  // See "Prompt Transforms" section: openrouter.ai/docs#transforms
  transforms?: string[];
  // See "Model Routing" section: openrouter.ai/docs#model-routing
  models?: string[];
  route?: 'fallback';
  // See "Provider Routing" section: openrouter.ai/docs#provider-routing
  provider?: ProviderPreferences;
};

// 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' | 'tool';
  // 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;
};

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;
      };
    };

请求头

OpenRouter 允许您指定一个可选的 HTTP-Referer 标头，以识别您的应用程序，并使其在 openrouter.ai 上对用户可见。您还可以包括一个可选的 X-Title 标头，以设置或修改您的应用程序的标题。例如：

typescript

fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${OPENROUTER_API_KEY}`,
    "HTTP-Referer": `${YOUR_SITE_URL}`,
    "X-Title": `${YOUR_SITE_NAME}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "mistralai/mixtral-8x7b-instruct",
    "messages": [
      {"role": "user", "content": "Who are you?"},
    ],
  })
});

**模型路由：**如果省略了 model 参数，则使用用户或付款人的默认值。否则，请记得从支持的模型或 API 中选择 model 的值，并包括组织前缀。OpenRouter 将选择最便宜和最好的 GPU 来处理请求，并在收到5xx 响应代码或受到速率限制时，退而求其次选择其他提供商或 GPU。

流式传输：服务器发送事件（SSE）也得到支持，以便为所有模型启用流式传输。只需在您的请求体中发送 stream: true 。SSE 流将偶尔包含一个“注释”有效负载，您应该忽略它（如下所示）。

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

**助手预填：**OpenRouter 支持要求模型完成部分响应。这对引导模型以特定方式响应可能很有用。

要使用这些功能，只需在您的 messages 数组末尾包含一条消息 role: "assistant" 。例如：

typescript

fetch("https://openrouter.ai/api/v1/chat/completions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${OPENROUTER_API_KEY}`,
    "HTTP-Referer": `${YOUR_SITE_URL}`,
    "X-Title": `${YOUR_SITE_NAME}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "model": "mistralai/mixtral-8x7b-instruct",
    "messages": [
      {"role": "user", "content": "Who are you?"},
      {"role": "assistant", "content": "I'm not sure, but my best guess is"},
    ],
  })
});

取消流式传输

对于一些提供商，流媒体请求可以通过中止连接或简单断开连接来取消。

当中断与支持流取消的提供商的连接时，模型将停止处理请求，并且一旦上游提供商检测到断开连接，计费将立即停止。

如果您正在使用Fetch API，您可以使用 AbortController 来取消流。这是一个例子：

typescript

const controller = new AbortController();

fetch('https://openrouter.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: ...,
  body: ...,
  signal: controller.signal
})

...

// Later, to cancel the stream:
controller.abort();

**注意：**中止/断开非流式请求或对不支持流取消的提供程序的流请求将不会停止模型在后台的处理。您仍将被收取剩余完成的费用。

响应

响应基本与 OpenAI Chat API 保持一致。这意味着， choices 始终是一个数组，即使模型只返回一个完成。如果请求了流，则每个选择都将包含一个 delta 属性，否则将包含一个 message 属性。这样可以更轻松地在所有模型中使用相同的代码。

在高层次上，OpenRouter 对模型和提供者之间的模式进行了规范化，因此您只需要学习一个模式。

响应主体

请注意， finish_reason 将根据模型提供商而有所不同。 model 属性告诉您在底层API中使用了哪个模型。

这是 TypeScript 类型的响应模式：

typescript

// Definitions of subtypes are below

type Response = {
  id: string;
  // Depending on whether you set "stream" to "true" and
  // whether you passed in "messages" or a "prompt", you
  // will get a different output shape
  choices: (NonStreamingChoice | StreamingChoice | NonChatChoice | Error)[];
  created: number; // Unix timestamp
  model: string;
  object: 'chat.completion' | 'chat.completion.chunk';
  // For non-streaming responses only. For streaming responses,
  // see "Querying Cost and Stats" below.
  usage?: {
    completion_tokens: number; // Equivalent to "native_tokens_completion" in the /generation API
    prompt_tokens: number; // Equivalent to "native_tokens_prompt"
    total_tokens: number; // Sum of the above two fields
    total_cost: number; // Number of credits used by this generation
  };
};

// Subtypes:

type NonChatChoice = {
  finish_reason: string | null;
  text: string;
};

type NonStreamingChoice = {
  finish_reason: string | null; // Depends on the model. Ex: 'stop' | 'length' | 'content_filter' | 'tool_calls' | 'function_call'
  message: {
    content: string | null;
    role: string;
    tool_calls?: ToolCall[];
    // Deprecated, replaced by tool_calls
    function_call?: FunctionCall;
  };
};

type StreamingChoice = {
  finish_reason: string | null;
  delta: {
    content: string | null;
    role?: string;
    tool_calls?: ToolCall[];
    // Deprecated, replaced by tool_calls
    function_call?: FunctionCall;
  };
};

type Error = {
  code: number; // See "Error Handling" section
  message: string;
};

type FunctionCall = {
  name: string;
  arguments: string; // JSON format arguments
};

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

下面是一个例子：

json

{
  "id": "gen-xxxxxxxxxxxxxx",
  "choices": [
    {
      "finish_reason": "stop", // Different models provide different reasons here
      "message": {
        // will be "delta" if streaming
        "role": "assistant",
        "content": "Hello there!"
      }
    }
  ],
  "model": "openai/gpt-3.5-turbo" // Could also be "anthropic/claude-2.1", etc, depending on the "model" that ends up being used
}

查询成本和统计数据

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

typescript

const generation = await fetch(
  "https://openrouter.ai/api/v1/generation?id=$GENERATION_ID",
  { headers }
)

await generation.json()
// OUTPUT:
{
  data: {
    "id": "gen-nNPYi0ZB6GOK5TNCUMHJGgXo",
    "model": "openai/gpt-4-32k",
    "streamed": false,
    "generation_time": 2,
    "created_at": "2023-09-02T20:29:18.574972+00:00",
    "tokens_prompt": 24,
    "tokens_completion": 29,
    "native_tokens_prompt": 24,
    "native_tokens_completion": 29,
    "num_media_prompt": null,
    "num_media_completion": null,
    "origin": "https://localhost:47323/",
    "total_cost": 0.00492
  }
};

请注意，对于非流式完成，令牌计数和 total_cost 也可以在响应主体的 usage 字段中找到。

SSE 流式注释

对于SSE流，我们偶尔需要发送 SSE 注释，以指示 OpenRouter 正在处理您的请求。这有助于防止连接超时。注释将如下所示：

shell

: OPENROUTER PROCESSING

根据SSE规范，可以安全地忽略评论负载。但是，您可以根据需要利用它来改善用户体验，例如显示动态加载指示器。

某些 SSE 客户端实现可能无法按照规范解析有效载荷，从而导致在对非 JSON 有效载荷进行 JSON.stringify 时出现未捕获错误。我们推荐使用以下客户端：

LLM 参数

typescript

temperature

可选项, float, 0.0 ~ 2.0
默认: 1.0
介绍视频：观看

这个设置会影响模型的回复多样性。较低的数值会导致更可预测和典型的回复，而较高的数值会鼓励更多样化和不太常见的回复。当数值为0时，模型对于相同的输入总是给出相同的回复。

typescript

top_p

可选项, float, 0.0 ~ 1.0
默认: 1.0
介绍视频：观看

该设置将模型的选择限制在可能令牌的百分比内：只有概率相加达到 P 的前几个令牌。较低的数值会使模型的响应更加可预测，而默认设置允许完整范围的令牌选择。可以将其视为动态的 Top-K。

typescript

top_k

可选项, integer, 0.0 or above
默认: 0
介绍视频：观看

这限制了模型在每一步的标记选择，使其从一个较小的集合中进行选择。值为 1 意味着模型将始终选择最有可能的下一个标记，导致可预测的结果。默认情况下，此设置被禁用，使模型考虑所有选择。

typescript

frequency_penalty

可选项, float, -2.0 ~ 2.0
默认: 0.0
介绍视频：观看

该设置旨在根据输入中出现的频率控制标记的重复。它试图更少地使用那些在输入中更频繁出现的标记，与它们出现的频率成比例。标记惩罚随出现次数增加而增加。负值将鼓励标记重复使用。

typescript

presence_penalty

可选项, float, -2.0 ~ 2.0
默认: 0.0
介绍视频：观看

调整模型重复输入中已使用的特定标记的频率。较高的值会减少这种重复的可能性，而负值则会产生相反的效果。标记惩罚不会随出现次数而缩放。负值会鼓励标记重复使用。

typescript

repetition_penalty

可选项, float, 0.0 ~ 2.0
默认: 1.0
介绍视频：观看

有助于减少输入中标记的重复。较高的值会使模型更不可能重复标记，但值过高会使输出缺乏连贯性（通常是由于缺少小词而导致的长句）。标记惩罚根据原始标记的概率进行缩放。

typescript

min_p

可选项, float, 0.0 ~ 1.0
默认: 0.0

表示一个标记被考虑的最小概率，相对于最可能标记的概率。（该值根据最可能标记的置信水平而变化。）如果您的 Min-P 设置为 0.1，那意味着它只允许概率至少为最佳选项的十分之一的标记。

typescript

top_a

可选项, float, 0.0 ~ 1.0
默认: 0.0

根据最有可能的标记的概率，只考虑具有“足够高”概率的顶级标记。可以将其视为动态的 Top-P。较低的 Top-A 值会基于最高概率的标记来聚焦选择，但范围更窄。较高的 Top-A 值不一定会影响输出的创造力，而是根据最大概率来细化过滤过程。

typescript

seed

可选项, integer

如果指定了，推理将以确定性方式进行采样，因此使用相同的种子和参数重复请求应该返回相同的结果。对于某些模型，确定性不能保证。

typescript

max_tokens

可选项, integer, 1 or above

这将设置模型在响应中生成的令牌数量的上限。它不会产生超过这个限制的令牌。最大值是上下文长度减去提示长度。

typescript

logit_bias

可选项, map

接受一个 JSON 对象，将令牌（由其在标记器中的令牌 ID 指定）映射到与之关联的偏置值，范围为 -100 到 100。在数学上，该偏置值将被添加到模型生成的 logit 值之前进行抽样。确切的影响将因模型而异，但在 -1 到 1 之间的值应该会减少或增加选择的可能性；像 -100 或 100 这样的值应该会导致相关令牌的禁止或独占选择。

typescript

logprobs

可选项, boolean

是否返回输出标记的对数概率。如果为真，则返回每个输出标记的对数概率。

typescript

top_logprobs

可选项, integer

一个介于 0 和 20 之间的整数，指定在每个标记位置返回的最有可能的标记数量，每个标记都有一个关联的对数概率。如果使用了这个参数，logprobs 必须设置为 true。

typescript

response_format

可选项, map

强制模型生成特定的输出格式。将其设置为 { "type": "json_object" } 可启用 JSON 模式，确保模型生成的消息是有效的 JSON。注意：在使用 JSON 模式时，您还应该通过系统或用户消息指示模型自行生成 JSON。

typescript

stop

可选项, array

如果模型遇到停止数组中指定的任何标记，即立即停止生成。

参数 API

OpenRouter 参数 API

提示词转换

OpenRouter 在选择发送 prompt 和发送ChatML messages 列表之间有一个简单的规则：

如果您希望 OpenRouter 根据您的请求选择适合的模板，请选择 messages 。可用的模板模式包括：
- alpaca（羊驼）：文档
- llama2：文档
- airoboros：文档
如果您想向模型发送自定义提示，请选择 prompt 。如果您想使用自定义指令模板或完全控制提交给模型的提示，这将非常有用。

为了帮助处理超出模型最大上下文大小的提示，OpenRouter 支持一个名为 transforms 的自定义参数：

typescript

{
  transforms: ["middle-out"], // Compress prompts > context size. This is the default for all models.
  messages: [...], // "prompt" works as well
  model // Works with any model
}

参数是一个字符串数组，告诉 OpenRouter 在将提示发送到模型之前应用一系列转换。转换按顺序应用。可用的转换包括：

middle-out ：将提示和消息链压缩到上下文大小。这有助于用户延长对话，部分原因是 LLMs 通常不太关注序列的中间部分。通过压缩或删除提示中间的消息来实现。

注意：所有 OpenRouter 模型默认使用 middle-out ，除非您在请求体中排除此转换，例如设置 transforms: [] 。

错误处理

对于错误，OpenRouter返回以下形状的JSON响应：

typescript

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

HTTP响应将具有与 error.code 相同的状态代码，如果形成请求错误：

Your original request is invalid（您的原始请求无效）
Your API key/account is out of credits（您的 API 密钥/账户已经用完了）

否则，返回的 HTTP 响应状态将为 200 ，并且在 LLM 生成输出时发生的任何错误将被发送到响应主体或作为 SSE 数据事件。

JavaScript 中打印错误的示例代码：

typescript

const request = await fetch('https://openrouter.ai/...');
console.log(request.status); // 除非模型开始处理您的请求，否则将显示错误代码
const response = await request.json();
console.error(response.error?.status); // 将显示错误代码
console.error(response.error?.message);

错误代码

400：错误的请求（无效或缺少参数，CORS）
401：凭证无效（OAuth 会话已过期，API 密钥已禁用/无效）
402：您的账户或 API 密钥的信用额度不足。请添加更多信用额度并重试请求。
403：您选择的模型需要进行审核，您的输入已被标记。
408：您的请求超时
429：您正在受到速率限制
502：您选择的模型已经关闭，或者我们从中收到了无效的响应。
503：没有符合您的路由要求的可用模型提供者

审核错误

如果您的输入被标记，错误元数据将包含有关问题的信息。元数据的形式如下：

typescript

type ModerationErrorMetadata = {
  reasons: string[]; // 您的输入为何被标记
  flagged_input: string; // 被标记的文本段，长度限制为 100 个字符。如果标记的输入长度超过 100 个字符，则会从中间截断并用... 取代。
};

限制

速率限制和剩余信用额

要检查 API 密钥的速率限制或剩余信用额度，请发出 GET 请求到：https://openrouter.ai/api/v1/auth/key

typescript

fetch('https://openrouter.ai/api/v1/auth/key', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer $OPENROUTER_API_KEY'
  }
});

如果您提交有效的 API 密钥，您应该会收到以下形式的响应：

typescript

type Key = {
  data: {
    label: string;
    usage: number; // 使用的积分数量
    limit: number | null; // 密钥的信用额度，无限制时为空
    is_free_tier: boolean; // 用户之前是否支付过积分
    rate_limit: {
      requests: number; // 允许的请求数...
      interval: string; // 在此区间内，例如："10s"
    };
  };
};

有两个全局速率限制适用于所有请求，无论帐户状态或模型可用性如何：

搜索限制：默认情况下，所有用户都受到每秒最多 200 个请求的最大速率限制，以防止拒绝服务攻击。如果您需要更高的限制，请通过 Discord 或使用我们的 support@ 电子邮件地址与我们联系。
免费限制：如果您使用免费模式（100%折扣，或以 :free 结尾的 ID），则每分钟请求将受到限制为10个。

对于所有其他请求，速率限制取决于密钥或账户上剩余的积分数量。对于您的 API 密钥可用的积分，您可以每秒使用 1 个积分进行 1 次请求，直到达到激增限制。

例如：

0 credits → 1 req/s (最小值)
5 credits → 5 req/s
10 credits → 10 req/s
1000 credits → 200 req/s (最大值)

如果您的账户余额为负数，您可能会看到 402 错误，包括免费模型。添加信用额度使您的余额超过零，可以再次使用这些模型。

Token 限制

一些用户可能在他们的账户上拥有的积分不足以发出昂贵的请求。OpenRouter 提供了一种在向任何模型发出请求之前知道这一点的方法。

为了获取用户可以生成的最大令牌数以及其提示中允许的最大令牌数，请在您的请求中添加身份验证标头到 https://openrouter.ai/api/v1/models ：

typescript

fetch('https://openrouter.ai/api/v1/models', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer $OPENROUTER_API_KEY'
  }
});

每个模型都将包括一个 per_request_limits 属性：

typescript

type Model = {
  id: string;
  pricing: {
    prompt: number;
    completion: number;
  };
  context_length: number;
  per_request_limits: {
    prompt_tokens: number;
    completion_tokens: number;
  };
};

其他框架

您可以在这个 Github 仓库中找到一些使用 OpenRouter 与其他框架的示例。以下是一些示例：

使用 npm i openai: github.
- *提示：您还可以使用 Grit 自动迁移您的代码。只需运行 npx @getgrit/launcher openrouter.
使用 Streamlit: github
使用 LangChain for Python: github
使用 LangChain.js: github

typescript

const chat = new ChatOpenAI({
  modelName: "anthropic/claude-instant-v1",
  temperature: 0.8,
  streaming: true,
  openAIApiKey: $OPENROUTER_API_KEY,
}, {
  basePath: $OPENROUTER_BASE_URL + "/api/v1",
  baseOptions: {
    headers: {
      "HTTP-Referer": "https://yourapp.com/",
      "X-Title": "Langchain.js Testing",
    },
  },
});

使用 Vercel AI SDK：

typescript

const config = new Configuration({
  basePath: $OPENROUTER_BASE_URL + "/api/v1",
  apiKey: $OPENROUTER_API_KEY,
  baseOptions: {
    headers: {
      "HTTP-Referer": "https://yourapp.com/",
      "X-Title": "Vercel Testing",
    }
  }
})

const openrouter = new OpenAIApi(config)

3D 对象（测试版）

OpenRouter 支持文本到 3D 对象生成，目前处于测试阶段。查看支持的媒体模型并尝试演示。要生成3D对象，请发送 POST 请求至 https://openrouter.ai/api/v1/objects/generations

shell

curl https://openrouter.ai/api/v1/objects/generations \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \\
  -H "HTTP-Referer: $YOUR_SITE_URL" \\
  -H "X-Title: $YOUR_SITE_NAME" \\
  -d '{
    "prompt": "a chair shaped like an avacado",
    "num_inference_steps": 32,
    "num_outputs": 1,
    "extension": "ply",
    "model": "openai/shap-e"
  }'

您应该收到一个类型为 MediaResponse 的响应。

typescript

// 每此生成都将包含一个 base64 字符串或一个托管的 url，或两者兼而有之。
interface MediaOutput {
  uri?: string; // base64 string
  url?: string; // hosted url
};

interface MediaResponse {
  generations: MediaOutput[];
};

OpenRouter 文档 ​

快速入门 ​

支持的模型 ​

提供商路由 ​

必需参数（测试版） ​

数据隐私 ​

禁用回退 ​

模型路由 ​

OAuth PKCE ​

API Keys ​

请求 ​

请求主体 ​

请求头 ​

取消流式传输 ​

响应 ​

响应主体 ​

查询成本和统计数据 ​

SSE 流式注释 ​

LLM 参数 ​

参数 API ​

提示词转换 ​

错误处理 ​

错误代码 ​

审核错误 ​

限制 ​

速率限制和剩余信用额 ​

Token 限制 ​

其他框架 ​

3D 对象（测试版） ​

OpenRouter 文档

快速入门

支持的模型

提供商路由

必需参数（测试版）

数据隐私

禁用回退

模型路由

OAuth PKCE

API Keys

请求

请求主体

请求头

取消流式传输

响应

响应主体

查询成本和统计数据

SSE 流式注释

LLM 参数

参数 API

提示词转换

错误处理

错误代码

审核错误

限制

速率限制和剩余信用额

Token 限制

其他框架

3D 对象（测试版）