API Reference

1
"messages": [
2
  {
3
    "role": "user",
4
    "content": [
5
      {
6
        "type": "text",
7
        "text": "What's in this image?"
8
      },
9
      {
10
        "type": "image_url",
11
        "image_url": {
12
          "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
13
        }
14
      }
15
    ]
16
  }
17
]

1
{
2
  "choices": [
3
    {
4
      "role": "assistant",
5
      "content": "This image depicts a scenic natural landscape featuring a long wooden boardwalk that stretches out through an expansive field of green grass. The boardwalk provides a clear path and invites exploration through the lush environment. The scene is surrounded by a variety of shrubbery and trees in the background, indicating a diverse plant life in the area."
6
    }
7
  ]
8
}

1
import { readFile } from "fs/promises";
2
3
const getFlowerImage = async (): Promise<string> => {
4
  const imagePath = new URL("flower.jpg", import.meta.url);
5
  const imageBuffer = await readFile(imagePath);
6
  const base64Image = imageBuffer.toString("base64");
7
  return `data:image/jpeg;base64,${base64Image}`;
8
};
9
10
...
11
12
"messages": [
13
  {
14
    role: "user",
15
    content: [
16
      {
17
        type: "text",
18
        text: "What's in this image?",
19
      },
20
      {
21
        type: "image_url",
22
        image_url: {
23
          url: `${await getFlowerImage()}`,
24
        },
25
      },
26
    ],
27
  },
28
];

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX///+/v7+jQ3Y5AAAADklEQVQI12P4AIX8EAgALgAD/aNpbtEAAAAASUVORK5CYII

1
...
2
"messages": [{
3
  "role": "user",
4
  "content": "What is the weather like in Boston?"
5
}],
6
"tools": [{
7
"type": "function",
8
"function": {
9
    "name": "get_current_weather",
10
    "description": "Get the current weather in a given location",
11
    "parameters": {
12
      "type": "object",
13
      "properties": {
14
        "location": {
15
          "type": "string",
16
          "description": "The city and state, e.g. San Francisco, CA"
17
        },
18
        "unit": {
19
          "type": "string",
20
          "enum": [
21
            "celsius",
22
            "fahrenheit"
23
          ]
24
        }
25
      },
26
      "required": [
27
        "location"
28
      ]
29
    }
30
  }
31
}]

1
// Some models might include their reasoning in content
2
"message": {
3
  "role": "assistant",
4
  "content": null,
5
  "tool_calls": [
6
    {
7
      "id": "call_9pw1qnYScqvGrCH58HWCvFH6",
8
      "type": "function",
9
      "function": {
10
        "name": "get_current_weather",
11
        "arguments": "{ \"location\": \"Boston, MA\"}"
12
      }
13
    }
14
  ]
15
},

1
const weather = await getWeather({ location: 'Boston, MA' });
2
console.log(weather); // { "temperature": "22", "unit": "celsius", "description": "Sunny"}

1
...
2
"messages": [
3
  {
4
    "role": "user",
5
    "content": "What is the weather like in Boston?"
6
  },
7
  {
8
    "role": "assistant",
9
    "content": null,
10
    "tool_calls": [
11
      {
12
        "id": "call_9pw1qnYScqvGrCH58HWCvFH6",
13
        "type": "function",
14
        "function": {
15
          "name": "get_current_weather",
16
          "arguments": "{ \"location\": \"Boston, MA\"}"
17
        }
18
      }
19
    ]
20
  },
21
  {
22
    "role": "tool",
23
    "name": "get_current_weather",
24
    "tool_call_id": "call_9pw1qnYScqvGrCH58HWCvFH6",
25
    "content": "{\"temperature\": \"22\", \"unit\": \"celsius\", \"description\": \"Sunny\"}"
26
  }
27
]

1
...
2
"message": {
3
  "role": "assistant",
4
  "content": "The current weather in Boston, MA is sunny with a temperature of 22°C."
5
}

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, you will get one usage object at
16
  // the end accompanied by an empty choices array.
17
  usage?: ResponseUsage;
18
};

1
// If the provider returns usage, we pass it down
2
// as-is. Otherwise, we count using the GPT-4 tokenizer.
3
4
type ResponseUsage = {
5
  /** Including images and tools if any */
6
  prompt_tokens: number;
7
  /** The tokens generated */
8
  completion_tokens: number;
9
  /** Sum of the above two fields */
10
  total_tokens: number;
11
};

1
// Subtypes:
2
type NonChatChoice = {
3
  finish_reason: string | null;
4
  text: string;
5
  error?: ErrorResponse;
6
};
7
8
type NonStreamingChoice = {
9
  finish_reason: string | null;
10
  native_finish_reason: string | null;
11
  message: {
12
    content: string | null;
13
    role: string;
14
    tool_calls?: ToolCall[];
15
  };
16
  error?: ErrorResponse;
17
};
18
19
type StreamingChoice = {
20
  finish_reason: string | null;
21
  native_finish_reason: string | null;
22
  delta: {
23
    content: string | null;
24
    role?: string;
25
    tool_calls?: ToolCall[];
26
  };
27
  error?: ErrorResponse;
28
};
29
30
type ErrorResponse = {
31
  code: number; // See "Error Handling" section
32
  message: string;
33
  metadata?: Record<string, unknown>; // Contains additional error information such as provider details, the raw error message, etc.
34
};
35
36
type ToolCall = {
37
  id: string;
38
  type: 'function';
39
  function: FunctionCall;
40
};

1
{
2
  "id": "gen-xxxxxxxxxxxxxx",
3
  "choices": [
4
    {
5
      "finish_reason": "stop", // Normalized finish_reason
6
      "native_finish_reason": "stop", // The raw finish_reason from the provider
7
      "message": {
8
        // will be "delta" if streaming
9
        "role": "assistant",
10
        "content": "Hello there!"
11
      }
12
    }
13
  ],
14
  "usage": {
15
    "prompt_tokens": 0,
16
    "completion_tokens": 4,
17
    "total_tokens": 4
18
  },
19
  "model": "openai/gpt-3.5-turbo" // Could also be "anthropic/claude-2.1", etc, depending on the "model" that ends up being used
20
}

: OPENROUTER PROCESSING