> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yourouter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Quickstart

> Connect your application to the YouRouter API in minutes

Use this guide to connect an application to YouRouter, make a test request, and verify the response shape. YouRouter exposes OpenAI-compatible endpoints at `https://api.yourouter.ai/v1`, so most existing OpenAI SDK integrations only need a base URL and API key change.

<Note>
  Need an API key? Create one in the [YouRouter Dashboard](https://platform.yourouter.ai/dashboard).
</Note>

## Integration Basics

| Item             | Value                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------- |
| Base URL         | `https://api.yourouter.ai/v1`                                                               |
| Auth header      | `Authorization: Bearer <YOUROUTER_API_KEY>`                                                 |
| Content type     | `Content-Type: application/json`                                                            |
| Model field      | Send the target model ID in `model`                                                         |
| Multimodal input | Send text and image blocks in `messages[].content`                                          |
| Default routing  | Omit `vendor`, or send `vendor: auto`                                                       |
| Pinned routing   | Send `vendor: openai`, `vendor: anthropic`, `vendor: google`, or another supported provider |

## 1. Set Your API Key

Store your API key in an environment variable before running the examples below.

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    export YOUROUTER_API_KEY="your-api-key-here"
    ```
  </Tab>

  <Tab title="Windows">
    ```cmd theme={null}
    set YOUROUTER_API_KEY=your-api-key-here
    ```
  </Tab>

  <Tab title=".env">
    ```bash theme={null}
    YOUROUTER_API_KEY=your-api-key-here
    ```
  </Tab>
</Tabs>

<Warning>
  Never expose your API key in browser-side code, mobile apps, public repositories, or client logs.
</Warning>

## 2. Make a Test Request

The fastest integration smoke test is a direct HTTP request to the Chat Completions endpoint. A successful response includes `choices[0].message.content`. Use cURL or any standard HTTP client; the examples below cover Python, Node.js, Go, Java, PHP, and Rust.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.yourouter.ai/v1/chat/completions \
      -H "Authorization: Bearer $YOUROUTER_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-4o",
        "messages": [
          {
            "role": "user",
            "content": "Reply with exactly: connected"
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="Python requests">
    ```bash theme={null}
    pip install requests
    ```

    ```python theme={null}
    import os
    import requests

    response = requests.post(
        "https://api.yourouter.ai/v1/chat/completions",
        headers={
            "Authorization": f"Bearer {os.environ['YOUROUTER_API_KEY']}",
            "Content-Type": "application/json",
        },
        json={
            "model": "gpt-4o",
            "messages": [
                {
                    "role": "user",
                    "content": "Reply with exactly: connected",
                }
            ],
        },
    )

    response.raise_for_status()
    print(response.json()["choices"][0]["message"]["content"])
    ```
  </Tab>

  <Tab title="Node.js 18+ fetch">
    ```javascript theme={null}
    // Save as quickstart.mjs and run with Node.js 18+.

    const response = await fetch('https://api.yourouter.ai/v1/chat/completions', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.YOUROUTER_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'gpt-4o',
        messages: [
          {
            role: 'user',
            content: 'Reply with exactly: connected',
          },
        ],
      }),
    });

    if (!response.ok) {
      throw new Error(await response.text());
    }

    const data = await response.json();
    console.log(data.choices[0].message.content);
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    package main

    import (
    	"bytes"
    	"encoding/json"
    	"fmt"
    	"io"
    	"net/http"
    	"os"
    )

    func main() {
    	payload, _ := json.Marshal(map[string]any{
    		"model": "gpt-4o",
    		"messages": []map[string]string{
    			{"role": "user", "content": "Reply with exactly: connected"},
    		},
    	})

    	req, err := http.NewRequest(
    		"POST",
    		"https://api.yourouter.ai/v1/chat/completions",
    		bytes.NewReader(payload),
    	)
    	if err != nil {
    		panic(err)
    	}

    	req.Header.Set("Authorization", "Bearer "+os.Getenv("YOUROUTER_API_KEY"))
    	req.Header.Set("Content-Type", "application/json")

    	res, err := http.DefaultClient.Do(req)
    	if err != nil {
    		panic(err)
    	}
    	defer res.Body.Close()

    	if res.StatusCode >= 400 {
    		body, _ := io.ReadAll(res.Body)
    		panic(fmt.Sprintf("request failed: %s\n%s", res.Status, body))
    	}

    	var result struct {
    		Choices []struct {
    			Message struct {
    				Content string `json:"content"`
    			} `json:"message"`
    		} `json:"choices"`
    	}

    	if err := json.NewDecoder(res.Body).Decode(&result); err != nil {
    		panic(err)
    	}

    	fmt.Println(result.Choices[0].Message.Content)
    }
    ```
  </Tab>

  <Tab title="Java 11+">
    ```java theme={null}
    import java.net.URI;
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;

    public class Quickstart {
        public static void main(String[] args) throws Exception {
            String body = String.join("\n",
                "{",
                "  \"model\": \"gpt-4o\",",
                "  \"messages\": [",
                "    {",
                "      \"role\": \"user\",",
                "      \"content\": \"Reply with exactly: connected\"",
                "    }",
                "  ]",
                "}"
            );

            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.yourouter.ai/v1/chat/completions"))
                .header("Authorization", "Bearer " + System.getenv("YOUROUTER_API_KEY"))
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(body))
                .build();

            HttpResponse<String> response = HttpClient.newHttpClient().send(
                request,
                HttpResponse.BodyHandlers.ofString()
            );

            if (response.statusCode() >= 400) {
                throw new RuntimeException(response.body());
            }

            System.out.println(response.body());
        }
    }
    ```
  </Tab>

  <Tab title="PHP">
    ```php theme={null}
    <?php

    $apiKey = getenv('YOUROUTER_API_KEY');

    $payload = json_encode([
        'model' => 'gpt-4o',
        'messages' => [
            [
                'role' => 'user',
                'content' => 'Reply with exactly: connected',
            ],
        ],
    ]);

    $ch = curl_init('https://api.yourouter.ai/v1/chat/completions');
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiKey,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => $payload,
    ]);

    $response = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    if ($response === false) {
        throw new RuntimeException(curl_error($ch));
    }

    curl_close($ch);

    if ($status >= 400) {
        throw new RuntimeException($response);
    }

    $data = json_decode($response, true);
    echo $data['choices'][0]['message']['content'] . PHP_EOL;
    ```
  </Tab>

  <Tab title="Rust">
    ```bash theme={null}
    cargo add reqwest --features blocking,json
    cargo add serde_json
    ```

    ```rust theme={null}
    use reqwest::blocking::Client;
    use serde_json::json;
    use std::env;

    fn main() -> Result<(), Box<dyn std::error::Error>> {
        let api_key = env::var("YOUROUTER_API_KEY")?;

        let response: serde_json::Value = Client::new()
            .post("https://api.yourouter.ai/v1/chat/completions")
            .bearer_auth(api_key)
            .json(&json!({
                "model": "gpt-4o",
                "messages": [
                    {
                        "role": "user",
                        "content": "Reply with exactly: connected"
                    }
                ]
            }))
            .send()?
            .error_for_status()?
            .json()?;

        if let Some(content) = response["choices"][0]["message"]["content"].as_str() {
            println!("{content}");
        }

        Ok(())
    }
    ```
  </Tab>
</Tabs>

## 3. Migrate Existing OpenAI SDK Code

If your app already uses the OpenAI SDK, keep your request body shape and update two fields: `api_key` and `base_url`.

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install openai
    ```

    ```python theme={null}
    import os
    from openai import OpenAI

    client = OpenAI(
        api_key=os.environ["YOUROUTER_API_KEY"],
        base_url="https://api.yourouter.ai/v1",
    )

    completion = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {
                "role": "user",
                "content": "Reply with exactly: connected",
            }
        ],
    )

    print(completion.choices[0].message.content)
    ```
  </Tab>

  <Tab title="Node.js">
    ```bash theme={null}
    npm install openai
    ```

    ```javascript theme={null}
    import OpenAI from 'openai';

    const openai = new OpenAI({
      apiKey: process.env.YOUROUTER_API_KEY,
      baseURL: 'https://api.yourouter.ai/v1',
    });

    const completion = await openai.chat.completions.create({
      model: 'gpt-4o',
      messages: [
        {
          role: 'user',
          content: 'Reply with exactly: connected',
        },
      ],
    });

    console.log(completion.choices[0].message.content);
    ```
  </Tab>
</Tabs>

<Note>
  For Go, Java, PHP, and Rust, use the same custom base URL pattern when your OpenAI-compatible SDK supports it. If the SDK does not expose a base URL option, call the `/v1/chat/completions` endpoint directly with the HTTP examples above.
</Note>

## 4. Choose a Model and Route

Choose a model by setting the `model` field. You can call many model families through the same API shape, such as OpenAI GPT models, Claude, Gemini, DeepSeek, Grok, Doubao, and Kimi. For vision and other multimodal inputs, see the [Multimodal guide](/guides/multimodal).

<Note>
  If an example model is not enabled for your account, replace it with any available model ID from the [YouRouter Dashboard](https://platform.yourouter.ai/dashboard).
</Note>

By default, YouRouter uses automatic routing. Omit the `vendor` header, or set `vendor: auto`, when you want YouRouter to choose the best available provider for the requested model.

Pin a request to a provider only when your integration depends on a specific upstream behavior, model variant, account, or compliance path.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.yourouter.ai/v1/chat/completions \
      -H "Authorization: Bearer $YOUROUTER_API_KEY" \
      -H "Content-Type: application/json" \
      -H "vendor: openai" \
      -d '{
        "model": "gpt-4o",
        "messages": [{"role": "user", "content": "Hello from a pinned provider."}]
      }'
    ```
  </Tab>

  <Tab title="Python SDK">
    ```python theme={null}
    completion = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello from a pinned provider."}],
        extra_headers={"vendor": "openai"},
    )
    ```
  </Tab>

  <Tab title="Node.js SDK">
    ```javascript theme={null}
    const completion = await openai.chat.completions.create({
      model: 'gpt-4o',
      messages: [{ role: 'user', content: 'Hello from a pinned provider.' }],
    }, {
      headers: { vendor: 'openai' },
    });
    ```
  </Tab>
</Tabs>

See [Models](/model) for model API examples and the [Router guide](/guides/router) for provider IDs, automatic failover behavior, and production recommendations.

## 5. Handle Responses and Errors

For OpenAI-compatible endpoints, successful responses follow the OpenAI response format. Read generated text from `choices[0].message.content`.

```json theme={null}
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "connected"
      }
    }
  ]
}
```

Common integration status codes:

| Status | Meaning                    | Integration action                   |
| ------ | -------------------------- | ------------------------------------ |
| `200`  | Request succeeded          | Parse the response body              |
| `401`  | Missing or invalid API key | Check the `Authorization` header     |
| `429`  | Upstream rate limit        | Retry with backoff or adjust routing |
| `500`  | Provider or gateway error  | Retry safely and log the request ID  |

## 6. Stream Responses

For chat UIs and agents, set `stream` to `true` to receive incremental chunks as the model generates text.

```python theme={null}
stream = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Explain automatic routing in two sentences."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="")
```

See [Create Chat Completion](/api-reference/chat/create#streaming) for the full request shape.

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Review endpoints, parameters, and response formats.
  </Card>

  <Card title="Models" icon="sparkles" href="/model">
    See how to pass model IDs and switch models through the API.
  </Card>

  <Card title="Multimodal" icon="image" href="/guides/multimodal">
    Send image inputs and call provider-native multimodal APIs.
  </Card>

  <Card title="Router Guide" icon="route" href="/guides/router">
    Learn when to use automatic routing or pin a provider.
  </Card>

  <Card title="Chat Completions" icon="message" href="/guides/chat-completions">
    Build conversations, streaming UIs, tools, and multimodal flows.
  </Card>
</CardGroup>