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

# Quickstart

> Get started with Nordlys in under 5 minutes

Get started with Nordlys by changing one line of code. No complex setup required.
Nordlys is a Mixture of Models model: each prompt activates the right models under the hood.

## Step 1: Get Your API Key

<Steps>
  <Step title="Sign Up">
    [Create a free account](https://www.nordlyslabs.com/api-platform/orgs) to get started
  </Step>

  <Step title="Generate Key">
    Generate your API key from the dashboard
  </Step>
</Steps>

## Step 2: Install SDK (Optional)

<Tabs>
  <Tab title="Nordlys SDK">
    <CodeGroup>
      ```bash pip theme={null}
      pip install nordlys-py
      ```

      ```bash uv theme={null}
      uv add nordlys-py
      ```

      ```bash poetry theme={null}
      poetry add nordlys-py
      ```
    </CodeGroup>

    <Note>Python only - native Nordlys SDK with Registry and Router APIs</Note>
  </Tab>

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

          ```bash uv theme={null}
          uv add openai
          ```

          ```bash poetry theme={null}
          poetry add openai
          ```
        </CodeGroup>
      </Tab>

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

          ```bash pnpm theme={null}
          pnpm add openai
          ```

          ```bash yarn theme={null}
          yarn add openai
          ```

          ```bash bun theme={null}
          bun add openai
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Anthropic SDK">
    <Tabs>
      <Tab title="Python">
        <CodeGroup>
          ```bash pip theme={null}
          pip install anthropic
          ```

          ```bash uv theme={null}
          uv add anthropic
          ```

          ```bash poetry theme={null}
          poetry add anthropic
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Node.js">
        <CodeGroup>
          ```bash npm theme={null}
          npm install @anthropic-ai/sdk
          ```

          ```bash pnpm theme={null}
          pnpm add @anthropic-ai/sdk
          ```

          ```bash yarn theme={null}
          yarn add @anthropic-ai/sdk
          ```

          ```bash bun theme={null}
          bun add @anthropic-ai/sdk
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Gemini SDK">
    <Tabs>
      <Tab title="Python">
        <CodeGroup>
          ```bash pip theme={null}
          pip install google-generativeai
          ```

          ```bash uv theme={null}
          uv add google-generativeai
          ```

          ```bash poetry theme={null}
          poetry add google-generativeai
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Node.js">
        <CodeGroup>
          ```bash npm theme={null}
          npm install @google/genai
          ```

          ```bash pnpm theme={null}
          pnpm add @google/genai
          ```

          ```bash yarn theme={null}
          yarn add @google/genai
          ```

          ```bash bun theme={null}
          bun add @google/genai
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Vercel AI SDK">
    <CodeGroup>
      ```bash npm theme={null}
      npm install ai @ai-sdk/openai
      ```

      ```bash pnpm theme={null}
      pnpm add ai @ai-sdk/openai
      ```

      ```bash yarn theme={null}
      yarn add ai @ai-sdk/openai
      ```

      ```bash bun theme={null}
      bun add ai @ai-sdk/openai
      ```
    </CodeGroup>

    <Note>Node.js only</Note>
  </Tab>

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

          ```bash uv theme={null}
          uv add langchain-openai
          ```

          ```bash poetry theme={null}
          poetry add langchain-openai
          ```
        </CodeGroup>
      </Tab>

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

          ```bash pnpm theme={null}
          pnpm add @langchain/openai
          ```

          ```bash yarn theme={null}
          yarn add @langchain/openai
          ```

          ```bash bun theme={null}
          bun add @langchain/openai
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="cURL">
    No installation required - cURL is available on most systems.
  </Tab>
</Tabs>

## Authentication

Nordlys uses API keys for authentication. Include your API key in requests:

* Header: `Authorization: Bearer YOUR_API_KEY`
* Store keys in environment variables (`NORDLYS_API_KEY`)

## Step 3: Make Your First Request

Choose your preferred language and framework:

<Tabs>
  <Tab title="Nordlys SDK">
    <CodeGroup>
      ```python Synchronous theme={null}
      from nordlys_py import Nordlys

      nordlys = Nordlys(api_key="your-nordlys-api-key")

      response = nordlys.chat.completions.create(
          model="nordlys/hypernova",
          messages=[{"role": "user", "content": "Hello!"}]
      )

      print(response.choices[0].message.content)
      ```

      ```python Asynchronous theme={null}
      import asyncio
      from nordlys_py import AsyncNordlys

      async def main():
          async with AsyncNordlys(api_key="your-nordlys-api-key") as nordlys:
              response = await nordlys.chat.completions.create(
                  model="nordlys/hypernova",
                  messages=[{"role": "user", "content": "Hello!"}]
              )
              print(response.choices[0].message.content)

      asyncio.run(main())
      ```
    </CodeGroup>
  </Tab>

  <Tab title="OpenAI SDK">
    <CodeGroup>
      ```javascript JavaScript/Node.js theme={null}
      import OpenAI from 'openai';

      const client = new OpenAI({
        apiKey: 'your-nordlys-api-key',
        baseURL: 'https://api.nordlyslabs.com/v1'
      });

      const response = await client.chat.completions.create({
        model: 'nordlys/hypernova',
        messages: [{ role: 'user', content: 'Hello!' }]
      });

      console.log(response.choices[0].message.content);
      ```

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

      client = OpenAI(
          api_key="your-nordlys-api-key",
          base_url="https://api.nordlyslabs.com/v1"
      )

      response = client.chat.completions.create(
          model="nordlys/hypernova",
          messages=[{"role": "user", "content": "Hello!"}]
      )

      print(response.choices[0].message.content)
      ```

      ```bash cURL theme={null}
      curl https://api.nordlyslabs.com/v1/chat/completions \
        -H "Content-Type: application/json" \
         -H "Authorization: Bearer apk_123456" \
        -d '{
          "model": "nordlys/hypernova",
          "messages": [{"role": "user", "content": "Hello!"}]
        }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Anthropic SDK">
    <CodeGroup>
      ```javascript JavaScript/Node.js theme={null}
      import Anthropic from '@anthropic-ai/sdk';

      const client = new Anthropic({
        apiKey: 'your-nordlys-api-key',
        baseURL: 'https://api.nordlyslabs.com/v1'
      });

      const response = await client.messages.create({
        model: 'nordlys/hypernova',
        max_tokens: 1000,
        messages: [{ role: 'user', content: 'Hello!' }]
      });

      console.log(response.content[0].text);
      ```

      ```python Python theme={null}
      import anthropic

      client = anthropic.Anthropic(
          api_key="your-nordlys-api-key",
          base_url="https://api.nordlyslabs.com/v1"
      )

      response = client.messages.create(
          model="nordlys/hypernova",
          max_tokens=1000,
          messages=[{"role": "user", "content": "Hello!"}]
      )

      print(response.content[0].text)
      ```

      ```bash cURL theme={null}
      curl https://api.nordlyslabs.com/v1/messages \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer apk_123456" \
        -H "anthropic-version: 2023-06-01" \
        -d '{
          "model": "nordlys/hypernova",
          "max_tokens": 1000,
          "messages": [{"role": "user", "content": "Hello!"}]
        }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Gemini SDK">
    <CodeGroup>
      ```javascript JavaScript/Node.js theme={null}
      import { GoogleGenerativeAI } from '@google/genai';

      const genAI = new GoogleGenerativeAI({
        apiKey: process.env.NORDLYS_API_KEY || 'your-nordlys-api-key',
        httpOptions: {
          baseUrl: 'https://api.nordlyslabs.com/v1beta'
        }
      });

      const model = genAI.getGenerativeModel({ model: 'nordlys/hypernova' });

      const result = await model.generateContent({
        contents: [
          {
            role: 'user',
            parts: [{ text: 'Hello!' }]
          }
        ],
        generationConfig: {
          maxOutputTokens: 512
        }
      });

      console.log(result.response.text());
      ```

      ```python Python theme={null}
      import os
      import google.generativeai as genai

      genai.configure(
          api_key=os.getenv("NORDLYS_API_KEY", "your-nordlys-api-key"),
          transport="rest",
          client_options={"api_endpoint": "https://api.nordlyslabs.com/v1beta"}
      )

      model = genai.GenerativeModel("nordlys/hypernova")

      response = model.generate_content(
          "Hello!",
          generation_config={"max_output_tokens": 512}
      )

      print(response.text)
      ```

      ```bash cURL theme={null}
      curl https://api.nordlyslabs.com/v1beta/models/nordlys/hypernova:generateContent \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer apk_123456" \
        -d '{
          "contents": [
            {
              "role": "user",
              "parts": [{"text": "Hello!"}]
            }
          ],
          "generationConfig": {
            "maxOutputTokens": 512
          }
        }'
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Vercel AI SDK">
    <CodeGroup>
      ```javascript Basic Text Generation theme={null}
      import { openai } from '@ai-sdk/openai';
      import { generateText } from 'ai';

      const { text } = await generateText({
        model: openai('nordlys/hypernova', {
          baseURL: 'https://api.nordlyslabs.com/v1',
          apiKey: 'your-nordlys-api-key'
        }),
        prompt: 'Hello!'
      });

      console.log(text);
      ```

      ```javascript Streaming theme={null}
      import { openai } from '@ai-sdk/openai';
      import { streamText } from 'ai';

      const { textStream } = await streamText({
        model: openai('nordlys/hypernova', {
          baseURL: 'https://api.nordlyslabs.com/v1',
          apiKey: 'your-nordlys-api-key'
        }),
        prompt: 'Write a story about AI'
      });

      for await (const delta of textStream) {
        process.stdout.write(delta);
      }
      ```

      ```javascript React Components theme={null}
      import { useChat } from 'ai/react';

      export default function Chat() {
        const { messages, input, handleInputChange, handleSubmit } = useChat({
          api: '/api/chat', // Your API route
          initialMessages: [{ role: 'system', content: 'Hello!' }]
        });

        return (
          <div>
            {messages.map(m => (
              <div key={m.id}>
                {m.role}: {m.content}
              </div>
            ))}
            <form onSubmit={handleSubmit}>
              <input value={input} onChange={handleInputChange} />
            </form>
          </div>
        );
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="LangChain">
    <CodeGroup>
      ```javascript JavaScript/Node.js theme={null}
      import { ChatOpenAI } from '@langchain/openai';

      const model = new ChatOpenAI({
        openAIApiKey: 'your-nordlys-api-key',
        configuration: {
          baseURL: 'https://api.nordlyslabs.com/v1'
        },
        modelName: 'nordlys/hypernova'
      });

      const response = await model.invoke('Hello!');
      console.log(response.content);
      ```

      ```python Python theme={null}
      from langchain_openai import ChatOpenAI

      model = ChatOpenAI(
          openai_api_key="your-nordlys-api-key",
          openai_api_base="https://api.nordlyslabs.com/v1",
          model_name="nordlys/hypernova"
      )

      response = model.invoke("Hello!")
      print(response.content)
      ```

      ```python Chains theme={null}
      from langchain_openai import ChatOpenAI
      from langchain.chains import AI modelChain
      from langchain.prompts import PromptTemplate

      model = ChatOpenAI(
          openai_api_key="your-nordlys-api-key",
          openai_api_base="https://api.nordlyslabs.com/v1",
          model_name="nordlys/hypernova"
      )

      prompt = PromptTemplate(
          input_variables=["topic"],
          template="Write a brief summary about {topic}"
      )

      chain = AI modelChain(llm=model, prompt=prompt)
      result = chain.run(topic="artificial intelligence")
      print(result)
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Error Handling

Always implement proper error handling in production. Nordlys provides detailed error information to help you build resilient applications.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    apiKey: process.env.NORDLYS_API_KEY,
    baseURL: 'https://api.nordlyslabs.com/v1'
  });

  async function chatWithRetry(message: string, maxRetries = 3) {
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        const response = await client.chat.completions.create({
          model: 'nordlys/hypernova',
          messages: [{ role: 'user', content: message }]
        });

        return response.choices[0].message.content;

      } catch (error: any) {
        console.error(`Attempt ${attempt} failed:`, error.message);

        if (attempt === maxRetries) throw error;

        // Exponential backoff
        await new Promise(resolve =>
          setTimeout(resolve, Math.pow(2, attempt) * 1000)
        );
      }
    }
  }

  // Usage
  try {
    const result = await chatWithRetry('Explain quantum computing');
    console.log(result);
  } catch (error) {
    console.error('All retries failed:', error);
    // Implement your preferred recovery behavior (message, etc.)
  }
  ```

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

  client = OpenAI(
      api_key=os.environ['NORDLYS_API_KEY'],
      base_url='https://api.nordlyslabs.com/v1'
  )

  def chat_with_retry(message: str, max_retries: int = 3):
      for attempt in range(1, max_retries + 1):
          try:
              response = client.chat.completions.create(
                  model='nordlys/hypernova',
                  messages=[{'role': 'user', 'content': message}]
              )
              return response.choices[0].message.content

          except Exception as error:
              print(f"Attempt {attempt} failed: {error}")

              if attempt == max_retries:
                  raise

              # Exponential backoff
              time.sleep(2 ** attempt)

  # Usage
  try:
      result = chat_with_retry('Explain quantum computing')
      print(result)
  except Exception as error:
      print(f"All retries failed: {error}")
      # Implement recovery behavior
  ```

  ```javascript JavaScript (Browser) theme={null}
  async function nordlysChat(messages, options = {}) {
    const { maxRetries = 3, recoveryMessage = 'Service temporarily unavailable' } = options;

    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        const response = await fetch('https://api.nordlyslabs.com/v1/chat/completions', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer apk_123456'
          },
          body: JSON.stringify({
            model: 'nordlys/hypernova',
            messages,
            temperature: 0.7
          })
        });

        if (!response.ok) {
          const errorData = await response.json();
          throw new Error(`API Error: ${errorData.error?.message || response.statusText}`);
        }

        const data = await response.json();
        return data.choices[0].message.content;

      } catch (error) {
        console.error(`Attempt ${attempt} failed:`, error.message);

        if (attempt === maxRetries) {
          return recoveryMessage;
        }

        // Exponential backoff
        await new Promise(resolve =>
          setTimeout(resolve, Math.pow(2, attempt) * 1000)
        );
      }
    }
  }

  // Usage
  const messages = [{ role: 'user', content: 'Hello!' }];
  const response = await nordlysChat(messages);
  console.log(response);
  ```
</CodeGroup>

<Note>
  **Production Tip**: Always log the `request_id` from error responses for debugging. For comprehensive error handling patterns, see the [Error Handling Best Practices](/guides/error-handling) guide.
</Note>

## Example Response

<CodeGroup>
  ```json OpenAI Format theme={null}
  {
    "id": "chatcmpl-abc123",
    "object": "chat.completion",
    "created": 1677652288,
    "model": "gpt-5-nano",
    "choices": [{
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! I'm ready to help you."
      },
      "finish_reason": "stop"
    }],
    "usage": {
      "prompt_tokens": 5,
      "completion_tokens": 10,
      "total_tokens": 15
    }
  }
  ```

  ```json Anthropic Format theme={null}
  {
    "id": "msg_abc123",
    "type": "message",
    "role": "assistant",
    "content": [{
      "type": "text",
      "text": "Hello! I'm ready to help you."
    }],
    "model": "claude-3-5-haiku",
    "stop_reason": "end_turn",
    "usage": {
      "input_tokens": 5,
      "output_tokens": 10
    }
  }
  ```
</CodeGroup>

<Note>
  Nordlys returns standard OpenAI or Anthropic-compatible responses.
</Note>

## Testing Your Integration

<Steps>
  <Step title="Send Test Request">
    Run your code with a simple message like "Hello!" to verify the connection
  </Step>

  <Step title="Check Response">
    Confirm you receive a response and check the `model` field in the response
  </Step>

  <Step title="Monitor Dashboard">
    View request logs and analytics in your [Nordlys dashboard](https://www.nordlyslabs.com/api-platform/orgs)
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Model Reference & Pricing" href="/model-reference" icon="lightbulb">
    Learn about Nordlys model specifications and pricing
  </Card>

  <Card title="Integration Guides" href="/integrations/openai-sdk" icon="book">
    Detailed guides for each SDK and framework
  </Card>

  <Card title="API Reference" href="/api-reference/chat-completions" icon="terminal">
    Complete API documentation with all parameters
  </Card>

  <Card title="Code Examples" href="/examples/basic-chat" icon="code">
    Working examples for common use cases
  </Card>
</CardGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="Troubleshooting" href="/troubleshooting" icon="wrench">
    Common issues and their solutions
  </Card>

  <Card title="Support" href="https://www.nordlyslabs.com/support" icon="life-ring">
    Get help from our team
  </Card>
</CardGroup>