Text Generation

Generate text with callModel using various input formats and model configurations. Supports multiple consumption patterns including text, streaming, and structured output.

Basic Usage

The simplest way to generate text:

1import { OpenRouter } from '@openrouter/sdk';
2
3const openrouter = new OpenRouter({
4 apiKey: process.env.OPENROUTER_API_KEY,
5});
6
7const result = openrouter.callModel({
8 model: 'openai/gpt-5-nano',
9 input: 'Explain quantum computing in one sentence.',
10});
11
12const text = await result.getText();

Input Formats

callModel accepts several input formats to match your use case.

String Input

The simplest format - a single string becomes a user message:

1const result = openrouter.callModel({
2 model: 'openai/gpt-5-nano',
3 input: 'What is the speed of light?',
4});

Message Array

For multi-turn conversations, pass an array of messages:

1const result = openrouter.callModel({
2 model: 'openai/gpt-5-nano',
3 input: [
4 { role: 'user', content: 'My name is Alice.' },
5 { role: 'assistant', content: 'Hello Alice! How can I help you today?' },
6 { role: 'user', content: 'What is my name?' },
7 ],
8});

Multimodal

For rich content including images:

1const result = openrouter.callModel({
2 model: 'openai/gpt-5.2',
3 input: [
4 {
5 type: 'message',
6 role: 'user',
7 content: [
8 { type: 'input_text', text: 'What is in this image?' },
9 {
10 type: 'input_image',
11 imageUrl: 'https://example.com/image.jpg',
12 detail: 'auto',
13 },
14 ],
15 },
16 ],
17});

System Instructions

Set the model’s behavior with the instructions parameter:

1const result = openrouter.callModel({
2 model: 'openai/gpt-5-nano',
3 instructions: 'You are a helpful coding assistant. Be concise and provide working code examples.',
4 input: 'How do I read a file in Node.js?',
5});

Model Selection

Single Model

Specify a model by its OpenRouter ID:

1const result = openrouter.callModel({
2 model: 'anthropic/claude-sonnet-4.5',
3 input: 'Hello!',
4});

Model Fallback

Provide multiple models for automatic fallback:

1const result = openrouter.callModel({
2 models: ['anthropic/claude-sonnet-4.5', 'openai/gpt-5.2', 'google/gemini-pro'],
3 input: 'Hello!',
4});

The SDK will try each model in order until one succeeds.

Response Methods

getText()

Returns just the text content after tool execution completes:

1const text = await result.getText();
2console.log(text); // "The speed of light is approximately 299,792 km/s."

getResponse()

Returns the full response object including usage data:

1const response = await result.getResponse();
2
3console.log(response.output); // Full output array
4console.log(response.usage); // Token usage information
5
6// Usage includes:
7// - inputTokens: tokens in the prompt
8// - outputTokens: tokens generated
9// - cachedTokens: tokens served from cache (cost savings)

Generation Parameters

Control the generation behavior:

1const result = openrouter.callModel({
2 model: 'openai/gpt-5-nano',
3 input: 'Write a creative story.',
4
5 // Temperature: 0 = deterministic, 2 = very creative
6 temperature: 0.7,
7
8 // Maximum tokens to generate
9 maxOutputTokens: 1000,
10
11 // Top-p sampling
12 topP: 0.9,
13});

Response Format

Request structured output:

1const result = openrouter.callModel({
2 model: 'openai/gpt-5-nano',
3 input: 'List three programming languages.',
4 text: {
5 format: {
6 type: 'json_object',
7 },
8 },
9});
10
11const text = await result.getText();
12const data = JSON.parse(text);

Error Handling

Handle common error cases:

1try {
2 const result = openrouter.callModel({
3 model: 'openai/gpt-5-nano',
4 input: 'Hello!',
5 });
6
7 const text = await result.getText();
8} catch (error) {
9 if (error instanceof Error && 'statusCode' in error) {
10 if (error.statusCode === 401) {
11 console.error('Invalid API key');
12 } else if (error.statusCode === 429) {
13 console.error('Rate limited - try again later');
14 } else if (error.statusCode === 503) {
15 console.error('Model unavailable');
16 }
17 } else {
18 console.error('Unexpected error:', error);
19 }
20}

Concurrent Requests

Each callModel invocation is independent:

1const [result1, result2, result3] = await Promise.all([
2 openrouter.callModel({ model: 'openai/gpt-5-nano', input: 'Question 1' }).getText(),
3 openrouter.callModel({ model: 'openai/gpt-5-nano', input: 'Question 2' }).getText(),
4 openrouter.callModel({ model: 'openai/gpt-5-nano', input: 'Question 3' }).getText(),
5]);

Next Steps

  • Streaming - Stream responses in real-time
  • Tools - Add tool capabilities to your generation
  • Message Formats - Convert from OpenAI/Claude formats