API Reference

1
// Definitions of subtypes are below
2
type Request = {
3
  // Either "messages" or "prompt" is required
4
  messages?: Message[];
5
  prompt?: string;
6
7
  // If "model" is unspecified, uses the user's default
8
  model?: string; // See "Supported Models" section
9
10
  // Allows to force the model to produce specific output format.
11
  // See "Structured Outputs" section below and models page for which models support it.
12
  response_format?: ResponseFormat;
13
14
  stop?: string | string[];
15
  stream?: boolean; // Enable streaming
16
  
17
  // Plugins to extend model capabilities (web search, PDF parsing, response healing)
18
  // See "Plugins" section: openrouter.ai/docs/guides/features/plugins
19
  plugins?: Plugin[];
20
21
  // See LLM Parameters (openrouter.ai/docs/api/reference/parameters)
22
  max_tokens?: number; // Range: [1, context_length)
23
  temperature?: number; // Range: [0, 2]
24
25
  // Tool calling
26
  // Will be passed down as-is for providers implementing OpenAI's interface.
27
  // For providers with custom interfaces, we transform and map the properties.
28
  // Otherwise, we transform the tools into a YAML template. The model responds with an assistant message.
29
  // See models supporting tool calling: openrouter.ai/models?supported_parameters=tools
30
  tools?: Tool[];
31
  tool_choice?: ToolChoice;
32
33
  // Advanced optional parameters
34
  seed?: number; // Integer only
35
  top_p?: number; // Range: (0, 1]
36
  top_k?: number; // Range: [1, Infinity) Not available for OpenAI models
37
  frequency_penalty?: number; // Range: [-2, 2]
38
  presence_penalty?: number; // Range: [-2, 2]
39
  repetition_penalty?: number; // Range: (0, 2]
40
  logit_bias?: { [key: number]: number };
41
  top_logprobs: number; // Integer only
42
  min_p?: number; // Range: [0, 1]
43
  top_a?: number; // Range: [0, 1]
44
45
  // Reduce latency by providing the model with a predicted output
46
  // https://platform.openai.com/docs/guides/latency-optimization#use-predicted-outputs
47
  prediction?: { type: 'content'; content: string };
48
49
  // OpenRouter-only parameters
50
  // See "Prompt Transforms" section: openrouter.ai/docs/guides/features/message-transforms
51
  transforms?: string[];
52
  // See "Model Routing" section: openrouter.ai/docs/guides/features/model-routing
53
  models?: string[];
54
  route?: 'fallback';
55
  // See "Provider Routing" section: openrouter.ai/docs/guides/routing/provider-selection
56
  provider?: ProviderPreferences;
57
  user?: string; // A stable identifier for your end-users. Used to help detect and prevent abuse.
58
  
59
  // Debug options (streaming only)
60
  debug?: {
61
    echo_upstream_body?: boolean; // If true, returns the transformed request body sent to the provider
62
  };
63
};
64
65
// Subtypes:
66
67
type TextContent = {
68
  type: 'text';
69
  text: string;
70
};
71
72
type ImageContentPart = {
73
  type: 'image_url';
74
  image_url: {
75
    url: string; // URL or base64 encoded image data
76
    detail?: string; // Optional, defaults to "auto"
77
  };
78
};
79
80
type ContentPart = TextContent | ImageContentPart;
81
82
type Message =
83
  | {
84
      role: 'user' | 'assistant' | 'system';
85
      // ContentParts are only for the "user" role:
86
      content: string | ContentPart[];
87
      // If "name" is included, it will be prepended like this
88
      // for non-OpenAI models: `{name}: {content}`
89
      name?: string;
90
    }
91
  | {
92
      role: 'tool';
93
      content: string;
94
      tool_call_id: string;
95
      name?: string;
96
    };
97
98
type FunctionDescription = {
99
  description?: string;
100
  name: string;
101
  parameters: object; // JSON Schema object
102
};
103
104
type Tool = {
105
  type: 'function';
106
  function: FunctionDescription;
107
};
108
109
type ToolChoice =
110
  | 'none'
111
  | 'auto'
112
  | {
113
      type: 'function';
114
      function: {
115
        name: string;
116
      };
117
    };
118
119
// Response format for structured outputs
120
type ResponseFormat =
121
  | { type: 'json_object' }
122
  | {
123
      type: 'json_schema';
124
      json_schema: {
125
        name: string;
126
        strict?: boolean;
127
        schema: object; // JSON Schema object
128
      };
129
    };
130
131
// Plugin configuration
132
type Plugin = {
133
  id: string; // 'web', 'file-parser', 'response-healing'
134
  enabled?: boolean;
135
  // Additional plugin-specific options
136
  [key: string]: unknown;
137
};

1
fetch('https://openrouter.ai/api/v1/chat/completions', {
2
  method: 'POST',
3
  headers: {
4
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
5
    'HTTP-Referer': '<YOUR_SITE_URL>', // Optional. Site URL for rankings on openrouter.ai.
6
    'X-Title': '<YOUR_SITE_NAME>', // Optional. Site title for rankings on openrouter.ai.
7
    'Content-Type': 'application/json',
8
  },
9
  body: JSON.stringify({
10
    model: 'openai/gpt-5.2',
11
    messages: [
12
      {
13
        role: 'user',
14
        content: 'What is the meaning of life?',
15
      },
16
    ],
17
  }),
18
});

1
fetch('https://openrouter.ai/api/v1/chat/completions', {
2
  method: 'POST',
3
  headers: {
4
    Authorization: 'Bearer <OPENROUTER_API_KEY>',
5
    'Content-Type': 'application/json',
6
  },
7
  body: JSON.stringify({
8
    model: 'openai/gpt-5.2',
9
    messages: [
10
      { role: 'user', content: 'What is the meaning of life?' },
11
      { role: 'assistant', content: "I'm not sure, but my best guess is" },
12
    ],
13
  }),
14
});

1
// Definitions of subtypes are below
2
type Response = {
3
  id: string;
4
  // Depending on whether you set "stream" to "true" and
5
  // whether you passed in "messages" or a "prompt", you
6
  // will get a different output shape
7
  choices: (NonStreamingChoice | StreamingChoice | NonChatChoice)[];
8
  created: number; // Unix timestamp
9
  model: string;
10
  object: 'chat.completion' | 'chat.completion.chunk';
11
12
  system_fingerprint?: string; // Only present if the provider supports it
13
14
  // Usage data is always returned for non-streaming.
15
  // When streaming, usage is returned exactly once in the final chunk
16
  // before the [DONE] message, with an empty choices array.
17
  usage?: ResponseUsage;
18
};

1
const generation = await fetch(
2
  'https://openrouter.ai/api/v1/generation?id=$GENERATION_ID',
3
  { headers },
4
);
5
6
const stats = await generation.json();