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

# Router.Chat.Completions SDK Reference

> SDK reference for the Router.Chat.Completions API, available in Node.js and Python.

## Router.Chat.Completions

### Create a Completion

Creates a model response for the given chat conversation with support for retries, fallbacks, prompts, and variables.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.router.chat.completions.create(messages=[], model="Model 3", fallbacks=[
          {
              "model": "openai/gpt-4o-mini",
          },
      ], retry={
          "on_codes": [
              429,
              500,
              502,
              503,
              504,
          ],
      }, cache={
          "ttl": 3600,
          "type": "exact_match",
      }, load_balancer={
          "type": "weight_based",
          "models": [
              {
                  "model": "openai/gpt-4o",
                  "weight": 0.7,
              },
              {
                  "model": "anthropic/claude-3-5-sonnet",
                  "weight": 0.3,
              },
          ],
      }, timeout={
          "call_timeout": 30000,
      }, variables={
          "customer_name": "John Smith",
          "product_name": "Premium Plan",
      }, stream=False)

      with res as event_stream:
          for event in event_stream:
              # handle event
              print(event, flush=True)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.router.chat.completions.create({
      messages: [],
      model: "Model 3",
      fallbacks: [
        {
          model: "openai/gpt-4o-mini",
        },
      ],
      retry: {
        onCodes: [
          429,
          500,
          502,
          503,
          504,
        ],
      },
      cache: {
        ttl: 3600,
        type: "exact_match",
      },
      loadBalancer: {
        type: "weight_based",
        models: [
          {
            model: "openai/gpt-4o",
            weight: 0.7,
          },
          {
            model: "anthropic/claude-3-5-sonnet",
            weight: 0.3,
          },
        ],
      },
      timeout: {
        callTimeout: 30000,
      },
      variables: {
        "customer_name": "John Smith",
        "product_name": "Premium Plan",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "messages": Union[CreateChatCompletionMessagesSystemMessage, CreateChatCompletionMessagesDeveloperMessage, CreateChatCompletionMessagesUserMessage, CreateChatCompletionMessagesAssistantMessage, CreateChatCompletionMessagesToolMessage],  # required
        "model": str,  # required
        "metadata": Dict[str, str],
        "name": Optional[str],
        "audio": {  # optional
            "voice": Literal["alloy", "echo", "fable", "onyx", "nova", "shimmer"],  # required
            "format_": Literal["wav", "mp3", "flac", "opus", "pcm16"],  # required
        },
        "frequency_penalty": OptionalNullable[float],
        "max_tokens": OptionalNullable[int],
        "max_completion_tokens": OptionalNullable[int],
        "logprobs": OptionalNullable[bool],
        "top_logprobs": OptionalNullable[int],
        "n": OptionalNullable[int],
        "presence_penalty": OptionalNullable[float],
        "response_format": Union[CreateChatCompletionResponseFormatText, CreateChatCompletionResponseFormatJSONObject, CreateChatCompletionResponseFormatJSONSchema],
        "reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh"]],
        "verbosity": Optional[str],
        "seed": OptionalNullable[float],
        "stop": Union[str, List[str]],
        "stream_options": {  # optional
            "include_usage": Optional[bool],
        },
        "thinking": Union[ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema],
        "temperature": OptionalNullable[float],
        "top_p": OptionalNullable[float],
        "top_k": OptionalNullable[float],
        "tools": {  # optional
            "type": Optional[Literal["function"]],
            "function": {  # required
                "name": str,  # required
                "description": Optional[str],
                "parameters": {  # optional
                    "type": Literal["object"],  # required
                    "properties": Dict[str, Any],  # required
                    "required": List[str],
                    "additional_properties": Optional[bool],
                },
                "strict": Optional[bool],
            },
        },
        "tool_choice": Union[CreateChatCompletionToolChoice1, CreateChatCompletionToolChoice2],
        "parallel_tool_calls": Optional[bool],
        "modalities": List[Literal["text", "audio"]],
        "guardrails": {  # optional
            "id": Union[CreateChatCompletionID1, str],  # required
            "execute_on": Literal["input", "output"],  # required
        },
        "plugins": Union[PIIRedactionPluginAuto, PIIRedactionPluginEn, PIIRedactionPluginNl],
        "fallbacks": {  # optional
            "model": str,  # required
        },
        "retry": {  # optional
            "count": Optional[float],
            "on_codes": List[float],
        },
        "cache": {  # optional
            "ttl": Optional[float],
            "type": Literal["exact_match"],  # required
        },
        "load_balancer": Union[CreateChatCompletionLoadBalancer1],
        "timeout": {  # optional
            "call_timeout": float,  # required
        },
        "variables": Dict[str, Any],
        "cache_control": {  # optional
            "type": Literal["ephemeral"],  # required
            "ttl": Optional[Literal["5m", "1h"]],
        },
        "prompt_cache_key": Optional[str],
        "orq": {  # optional
            "name": Optional[str],
            "retry": {  # optional
                "count": Optional[float],
                "on_codes": List[float],
            },
            "fallbacks": {  # optional
                "model": str,  # required
            },
            "prompt": {  # optional
                "id": str,  # required
                "version": Literal["latest"],  # required
            },
            "identity": {  # optional
                "id": str,  # required
                "display_name": Optional[str],
                "email": Optional[str],
                "metadata": List[Dict[str, Any]],
                "logo_url": Optional[str],
                "tags": List[str],
            },
            "~~`contact`~~": {  # optional
                "id": str,  # required
                "display_name": Optional[str],
                "email": Optional[str],
                "metadata": List[Dict[str, Any]],
                "logo_url": Optional[str],
                "tags": List[str],
            },
            "thread": {  # optional
                "id": str,  # required
                "tags": List[str],
            },
            "~~`inputs`~~": Union[Dict[str, Any], List[Inputs2]],
            "cache": {  # optional
                "ttl": Optional[float],
                "type": Literal["exact_match"],  # required
            },
            "knowledge_bases": {  # optional
                "top_k": Optional[int],
                "threshold": Optional[float],
                "search_type": Optional[Literal["vector_search", "keyword_search", "hybrid_search"]],
                "filter_by": Union[Dict[str, CreateChatCompletionFilterBy1], CreateChatCompletionFilterByAnd, CreateChatCompletionFilterByOr],
                "search_options": {  # optional
                    "include_vectors": Optional[bool],
                    "include_metadata": Optional[bool],
                    "include_scores": Optional[bool],
                },
                "rerank_config": {  # optional
                    "model": str,  # required
                    "threshold": Optional[float],
                    "top_k": Optional[int],
                },
                "agentic_rag_config": {  # optional
                    "model": str,  # required
                },
                "knowledge_id": str,  # required
                "query": Optional[str],
            },
            "load_balancer": Union[CreateChatCompletionLoadBalancerRouterChatCompletions1],
            "timeout": {  # optional
                "call_timeout": float,  # required
            },
        },
        "stream": Optional[bool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      messages: string;  // required
      model: string;  // required
      metadata?: Record<string, string>;
      name?: string;
      audio?: {
        voice: string;  // required
        format: string;  // required
      };
      frequencyPenalty?: number;
      maxTokens?: number;
      maxCompletionTokens?: number;
      logprobs?: boolean;
      topLogprobs?: number;
      n?: number;
      presencePenalty?: number;
      responseFormat?: string;
      reasoningEffort?: string;
      verbosity?: string;
      seed?: number;
      stop?: string | string[];
      streamOptions?: {
        includeUsage?: boolean;
      };
      thinking?: string;
      temperature?: number;
      topP?: number;
      topK?: number;
      tools?: {
        type?: string;
        function: {  // required
          name: string;  // required
          description?: string;
          parameters?: {
            type: string;  // required
            properties: Record<string, any>;  // required
            required?: string[];
            additionalProperties?: boolean;
          };
          strict?: boolean;
        };
      };
      toolChoice?: string;
      parallelToolCalls?: boolean;
      modalities?: string;
      guardrails?: {
        id: string;  // required
        executeOn: string;  // required
      };
      plugins?: string;
      fallbacks?: {
        model: string;  // required
      };
      retry?: {
        count?: number;
        onCodes?: number[];
      };
      cache?: {
        ttl?: number;
        type: string;  // required
      };
      loadBalancer?: string;
      timeout?: {
        callTimeout: number;  // required
      };
      variables?: Record<string, any>;
      cacheControl?: {
        type: string;  // required
        ttl?: string;
      };
      promptCacheKey?: string;
      ~~`orq`~~?: {
        name?: string;
        retry?: {
          count?: number;
          onCodes?: number[];
        };
        fallbacks?: {
          model: string;  // required
        };
        prompt?: {
          id: string;  // required
          version: string;  // required
        };
        identity?: {
          id: string;  // required
          displayName?: string;
          email?: string;
          metadata?: Record<string, any>[];
          logoUrl?: string;
          tags?: string[];
        };
        ~~`contact`~~?: {
          id: string;  // required
          displayName?: string;
          email?: string;
          metadata?: Record<string, any>[];
          logoUrl?: string;
          tags?: string[];
        };
        thread?: {
          id: string;  // required
          tags?: string[];
        };
        ~~`inputs`~~?: string;
        cache?: {
          ttl?: number;
          type: string;  // required
        };
        knowledgeBases?: {
          topK?: number;
          threshold?: number;
          searchType?: string;
          filterBy?: string;
          searchOptions?: {
            includeVectors?: boolean;
            includeMetadata?: boolean;
            includeScores?: boolean;
          };
          rerankConfig?: {
            model: string;  // required
            threshold?: number;
            topK?: number;
          };
          agenticRagConfig?: {
            model: string;  // required
          };
          knowledgeId: string;  // required
          query?: string;
        };
        loadBalancer?: string;
        timeout?: {
          callTimeout: number;  // required
        };
      };
      stream?: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "choices": {
            "finish_reason": Nullable[CreateChatCompletionFinishReason],
            "index": Optional[float],
            "message": {
                "content": OptionalNullable[str],
                "refusal": OptionalNullable[str],
                "tool_calls": {  # optional
                    "index": Optional[float],
                    "id": Optional[str],
                    "type": Optional[Literal["function"]],
                    "function": {  # optional
                        "name": Optional[str],
                        "arguments": Optional[str],
                    },
                    "thought_signature": Optional[str],
                },
                "role": Optional[Literal["assistant"]],
                "reasoning": OptionalNullable[str],
                "reasoning_signature": OptionalNullable[str],
                "redacted_reasoning": Optional[str],
                "audio": {  # optional
                    "id": str,
                    "expires_at": int,
                    "data": str,
                    "transcript": str,
                },
            },
            "logprobs": {  # optional
                "content": {
                    "token": str,
                    "logprob": float,
                    "bytes_": List[float],
                    "top_logprobs": {
                        "token": str,
                        "logprob": float,
                        "bytes_": List[float],
                    },
                },
                "refusal": {
                    "token": str,
                    "logprob": float,
                    "bytes_": List[float],
                    "top_logprobs": {
                        "token": str,
                        "logprob": float,
                        "bytes_": List[float],
                    },
                },
            },
        },
        "created": float,
        "model": str,
        "system_fingerprint": OptionalNullable[str],
        "usage": {  # optional
            "completion_tokens": Optional[float],
            "prompt_tokens": Optional[float],
            "total_tokens": Optional[float],
            "prompt_tokens_details": {  # optional
                "cached_tokens": OptionalNullable[int],
                "cache_creation_tokens": OptionalNullable[int],
                "audio_tokens": OptionalNullable[int],
            },
            "completion_tokens_details": {  # optional
                "reasoning_tokens": OptionalNullable[float],
                "accepted_prediction_tokens": OptionalNullable[float],
                "rejected_prediction_tokens": OptionalNullable[float],
                "audio_tokens": OptionalNullable[int],
            },
        },
        "object": Literal["chat.completion"],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      choices: {
        finish_reason: Nullable[CreateChatCompletionFinishReason];
        index?: number | undefined;
        message: {
          content?: string | null | undefined;
          refusal?: string | null | undefined;
          tool_calls?: {
            index?: number | undefined;
            id?: string | undefined;
            type?: "function" | undefined;
            function?: {
              name?: string | undefined;
              arguments?: string | undefined;
            };
            thought_signature?: string | undefined;
          };
          role?: "assistant" | undefined;
          reasoning?: string | null | undefined;
          reasoning_signature?: string | null | undefined;
          redacted_reasoning?: string | undefined;
          audio?: {
            id: string;
            expires_at: number;
            data: string;
            transcript: string;
          };
        };
        logprobs?: {
          content: {
            token: string;
            logprob: number;
            bytes_: number[];
            top_logprobs: {
              token: string;
              logprob: number;
              bytes_: number[];
            };
          };
          refusal: {
            token: string;
            logprob: number;
            bytes_: number[];
            top_logprobs: {
              token: string;
              logprob: number;
              bytes_: number[];
            };
          };
        };
      };
      created: number;
      model: string;
      system_fingerprint?: string | null | undefined;
      usage?: {
        completion_tokens?: number | undefined;
        prompt_tokens?: number | undefined;
        total_tokens?: number | undefined;
        prompt_tokens_details?: {
          cached_tokens?: number | null | undefined;
          cache_creation_tokens?: number | null | undefined;
          audio_tokens?: number | null | undefined;
        };
        completion_tokens_details?: {
          reasoning_tokens?: number | null | undefined;
          accepted_prediction_tokens?: number | null | undefined;
          rejected_prediction_tokens?: number | null | undefined;
          audio_tokens?: number | null | undefined;
        };
      };
      object: "chat.completion";
    }
    ```
  </CodeGroup>
</Expandable>