# API Reference

> Complete API reference for callModel, ModelResult, tool types, and helper functions in the OpenRouter SDK.

## callModel

```typescript
function callModel(request: CallModelInput, options?: RequestOptions): ModelResult
```

Creates a response using the OpenResponses API with multiple consumption patterns.

### CallModelInput

| Parameter            | Type                                       | Required | Description                          |
| -------------------- | ------------------------------------------ | -------- | ------------------------------------ |
| `model`              | `string \| ((ctx: TurnContext) => string)` | Yes\*    | Model ID (e.g., "openai/gpt-5-nano") |
| `models`             | `string[]`                                 | Yes\*    | Model fallback array                 |
| `input`              | `OpenResponsesInput`                       | Yes      | Input messages or string             |
| `instructions`       | `string \| ((ctx: TurnContext) => string)` | No       | System instructions                  |
| `tools`              | `Tool[]`                                   | No       | Tools available to the model         |
| `maxToolRounds`      | `MaxToolRounds`                            | No       | Tool execution limit (deprecated)    |
| `stopWhen`           | `StopWhen`                                 | No       | Stop conditions                      |
| `temperature`        | `number \| ((ctx: TurnContext) => number)` | No       | Sampling temperature (0-2)           |
| `maxOutputTokens`    | `number \| ((ctx: TurnContext) => number)` | No       | Maximum tokens to generate           |
| `topP`               | `number`                                   | No       | Top-p sampling                       |
| `text`               | `ResponseTextConfig`                       | No       | Text format configuration            |
| `provider`           | `ProviderPreferences`                      | No       | Provider routing and configuration   |
| `topK`               | `number`                                   | No       | Top-k sampling                       |
| `metadata`           | `Record<string, string>`                   | No       | Request metadata                     |
| `toolChoice`         | `ToolChoice`                               | No       | Tool choice configuration            |
| `parallelToolCalls`  | `boolean`                                  | No       | Enable parallel tool calling         |
| `reasoning`          | `ReasoningConfig`                          | No       | Reasoning configuration              |
| `promptCacheKey`     | `string`                                   | No       | Cache key for prompt caching         |
| `previousResponseId` | `string`                                   | No       | Context from previous response       |
| `include`            | `string[]`                                 | No       | Include extra fields in response     |
| `background`         | `boolean`                                  | No       | Run request in background            |
| `safetyIdentifier`   | `string`                                   | No       | User safety identifier               |
| `serviceTier`        | `string`                                   | No       | Service tier preference              |
| `truncation`         | `string`                                   | No       | Truncation mode                      |
| `plugins`            | `Plugin[]`                                 | No       | Enabled plugins                      |
| `user`               | `string`                                   | No       | End-user identifier                  |
| `sessionId`          | `string`                                   | No       | Session identifier                   |
| `store`              | `boolean`                                  | No       | Store request data                   |

\*Either `model` or `models` is required.

### ProviderPreferences

Configuration for routing and provider selection.

| Parameter                | Type                | Description                                                        |
| ------------------------ | ------------------- | ------------------------------------------------------------------ |
| `allowFallbacks`         | `boolean`           | Allow backup providers when primary is unavailable (default: true) |
| `requireParameters`      | `boolean`           | Only use providers that support all requested parameters           |
| `dataCollection`         | `"allow" \| "deny"` | Data collection policy (allow/deny)                                |
| `order`                  | `string[]`          | Custom provider routing order                                      |
| `only`                   | `string[]`          | Restrict to specific providers                                     |
| `ignore`                 | `string[]`          | Exclude specific providers                                         |
| `quantizations`          | `string[]`          | Filter by quantization levels                                      |
| `sort`                   | `string`            | Load balancing strategy (e.g., "throughput")                       |
| `maxPrice`               | `object`            | Maximum price limits                                               |
| `preferredMinThroughput` | `number`            | Minimum tokens per second preference                               |
| `preferredMaxLatency`    | `number`            | Maximum latency preference                                         |

### RequestOptions

| Parameter | Type          | Description                     |
| --------- | ------------- | ------------------------------- |
| `timeout` | `number`      | Request timeout in milliseconds |
| `signal`  | `AbortSignal` | Abort signal for cancellation   |

***

## ModelResult

Wrapper providing multiple consumption patterns for a response.

### Methods

#### getText()

```typescript
getText(): Promise<string>
```

Get text content after tool execution completes.

#### getResponse()

```typescript
getResponse(): Promise<OpenResponsesNonStreamingResponse>
```

Get full response with usage data (inputTokens, outputTokens, cachedTokens).

#### getTextStream()

```typescript
getTextStream(): AsyncIterableIterator<string>
```

Stream text deltas.

#### getReasoningStream()

```typescript
getReasoningStream(): AsyncIterableIterator<string>
```

Stream reasoning deltas (for reasoning models).

#### getNewMessagesStream()

```typescript
getNewMessagesStream(): AsyncIterableIterator<ResponsesOutputMessage | OpenResponsesFunctionCallOutput>
```

Stream incremental message updates in OpenResponses format.

#### getFullResponsesStream()

```typescript
getFullResponsesStream(): AsyncIterableIterator<EnhancedResponseStreamEvent>
```

Stream all events including tool preliminary results.

#### getToolCalls()

```typescript
getToolCalls(): Promise<ParsedToolCall[]>
```

Get all tool calls from initial response.

#### getToolCallsStream()

```typescript
getToolCallsStream(): AsyncIterableIterator<ParsedToolCall>
```

Stream tool calls as they complete.

#### getToolStream()

```typescript
getToolStream(): AsyncIterableIterator<ToolStreamEvent>
```

Stream tool deltas and preliminary results.

#### cancel()

```typescript
cancel(): Promise<void>
```

Cancel the stream and all consumers.

***

## Tool Types

### tool()

```typescript
function tool<TInput, TOutput>(config: ToolConfig): Tool
```

Create a typed tool with Zod schema validation.

### ToolConfig

| Parameter        | Type                      | Required | Description                            |
| ---------------- | ------------------------- | -------- | -------------------------------------- |
| `name`           | `string`                  | Yes      | Tool name                              |
| `description`    | `string`                  | No       | Tool description                       |
| `inputSchema`    | `ZodObject`               | Yes      | Input parameter schema                 |
| `outputSchema`   | `ZodType`                 | No       | Output schema                          |
| `eventSchema`    | `ZodType`                 | No       | Event schema (triggers generator mode) |
| `execute`        | `function \| false`       | Yes      | Execute function or false for manual   |
| `nextTurnParams` | `NextTurnParamsFunctions` | No       | Parameters to modify next turn         |

### Tool

Union type of all tool types:

```typescript
type Tool =
  | ToolWithExecute<ZodObject, ZodType>
  | ToolWithGenerator<ZodObject, ZodType, ZodType>
  | ManualTool<ZodObject, ZodType>;
```

### ToolWithExecute

Regular tool with execute function:

```typescript
interface ToolWithExecute<TInput, TOutput> {
  type: ToolType.Function;
  function: {
    name: string;
    description?: string;
    inputSchema: TInput;
    outputSchema?: TOutput;
    execute: (params: z.infer<TInput>, context?: TurnContext) => Promise<z.infer<TOutput>>;
  };
}
```

### ToolWithGenerator

Generator tool with eventSchema:

```typescript
interface ToolWithGenerator<TInput, TEvent, TOutput> {
  type: ToolType.Function;
  function: {
    name: string;
    description?: string;
    inputSchema: TInput;
    eventSchema: TEvent;
    outputSchema: TOutput;
    execute: (params: z.infer<TInput>, context?: TurnContext) => AsyncGenerator<z.infer<TEvent>>;
  };
}
```

### ManualTool

Tool without execute function:

```typescript
interface ManualTool<TInput, TOutput> {
  type: ToolType.Function;
  function: {
    name: string;
    description?: string;
    inputSchema: TInput;
    outputSchema?: TOutput;
  };
}
```

***

## Context Types

### TurnContext

```typescript
interface TurnContext {
  toolCall?: OpenResponsesFunctionToolCall;
  numberOfTurns: number;
  turnRequest?: OpenResponsesRequest;
}
```

### NextTurnParamsContext

```typescript
interface NextTurnParamsContext {
  input: OpenResponsesInput;
  model: string;
  models: string[];
  temperature: number | null;
  maxOutputTokens: number | null;
  topP: number | null;
  topK?: number | undefined;
  instructions: string | null;
}
```

***

## Stream Event Types

### EnhancedResponseStreamEvent

```typescript
type EnhancedResponseStreamEvent =
  | OpenResponsesStreamEvent
  | ToolPreliminaryResultEvent;
```

### ToolStreamEvent

```typescript
type ToolStreamEvent =
  | { type: 'delta'; content: string }
  | { type: 'preliminary_result'; toolCallId: string; result: unknown };
```

### ParsedToolCall

```typescript
interface ParsedToolCall {
  id: string;
  name: string;
  arguments: unknown;
}
```

### ToolExecutionResult

```typescript
interface ToolExecutionResult {
  toolCallId: string;
  toolName: string;
  result: unknown;
  preliminaryResults?: unknown[];
  error?: Error;
}
```

***

## Stop Conditions

### StopWhen

```typescript
type StopWhen =
  | StopCondition
  | StopCondition[];
```

### StopCondition

```typescript
type StopCondition = (context: StopConditionContext) => boolean | Promise<boolean>;
```

### StopConditionContext

```typescript
interface StopConditionContext {
  steps: StepResult[];
}
```

### StepResult

```typescript
interface StepResult {
  stepType: 'initial' | 'continue';
  text: string;
  toolCalls: TypedToolCallUnion[];
  toolResults: ToolExecutionResultUnion[];
  response: OpenResponsesNonStreamingResponse;
  usage?: OpenResponsesUsage;
  finishReason?: string;
  warnings?: Warning[];
  experimental_providerMetadata?: Record<string, unknown>;
}
```

### Warning

```typescript
interface Warning {
  type: string;
  message: string;
}
```

### Built-in Helpers

| Function         | Signature                           | Description              |
| ---------------- | ----------------------------------- | ------------------------ |
| `stepCountIs`    | `(n: number) => StopCondition`      | Stop after n steps       |
| `hasToolCall`    | `(name: string) => StopCondition`   | Stop when tool is called |
| `maxTokensUsed`  | `(n: number) => StopCondition`      | Stop after n tokens      |
| `maxCost`        | `(amount: number) => StopCondition` | Stop after cost limit    |
| `finishReasonIs` | `(reason: string) => StopCondition` | Stop on finish reason    |

***

## Format Helpers

### fromChatMessages

```typescript
function fromChatMessages(messages: Message[]): OpenResponsesInput
```

Convert OpenAI chat format to OpenResponses input.

### toChatMessage

```typescript
function toChatMessage(response: OpenResponsesNonStreamingResponse): AssistantMessage
```

Convert response to chat message format.

### fromClaudeMessages

```typescript
function fromClaudeMessages(messages: ClaudeMessageParam[]): OpenResponsesInput
```

Convert Anthropic Claude format to OpenResponses input.

### toClaudeMessage

```typescript
function toClaudeMessage(response: OpenResponsesNonStreamingResponse): ClaudeMessage
```

Convert response to Claude message format.

***

## Type Utilities

### InferToolInput

```typescript
type InferToolInput<T> = T extends { function: { inputSchema: infer S } }
  ? S extends ZodType ? z.infer<S> : unknown
  : unknown;
```

### InferToolOutput

```typescript
type InferToolOutput<T> = T extends { function: { outputSchema: infer S } }
  ? S extends ZodType ? z.infer<S> : unknown
  : unknown;
```

### InferToolEvent

```typescript
type InferToolEvent<T> = T extends { function: { eventSchema: infer S } }
  ? S extends ZodType ? z.infer<S> : never
  : never;
```

### TypedToolCall

```typescript
type TypedToolCall<T extends Tool> = {
  id: string;
  name: T extends { function: { name: infer N } } ? N : string;
  arguments: InferToolInput<T>;
};
```

***

## Exports

```typescript
// Main SDK
export { OpenRouter } from '@openrouter/sdk';

// Tool helpers
export { tool, ToolType } from '@openrouter/sdk';

// Format helpers
export { fromChatMessages, toChatMessage, fromClaudeMessages, toClaudeMessage } from '@openrouter/sdk';

// Stop condition helpers
export { stepCountIs, hasToolCall, maxTokensUsed, maxCost, finishReasonIs } from '@openrouter/sdk';

// Types
export type {
  CallModelInput,
  Tool,
  ToolWithExecute,
  ToolWithGenerator,
  ManualTool,
  TurnContext,
  ParsedToolCall,
  ToolExecutionResult,
  StopCondition,
  StopWhen,
  MaxToolRounds,
  InferToolInput,
  InferToolOutput,
  InferToolEvent,
} from '@openrouter/sdk';
```