Chat completions

Use nirmos.gateway.chat.create for non-streaming chat completions.

const completion = await nirmos.gateway.chat.create({
  model: "openai/gpt-4.1",
  messages: [
    {
      role: "system",
      content: "You are a concise technical editor.",
    },
    {
      role: "user",
      content: "Rewrite this release note: caching got better",
    },
  ],
  temperature: 0.2,
  maxOutputTokens: 300,
});

Request fields

Field	Type	Description
`model`	`string`	Nirmos model identifier
`messages`	`ChatMessage[]`	Conversation messages
`prompt`	`PromptReference`	Managed prompt to render and insert
`temperature`	`number`	Sampling temperature
`topP`	`number`	Nucleus sampling threshold
`maxOutputTokens`	`number`	Maximum generated tokens
`stop`	`string \| string[]`	Stop sequence or sequences
`tools`	`FunctionTool[]`	Function definitions
`toolChoice`	`ToolChoice`	Tool selection behavior
`responseFormat`	`ResponseFormat`	Text, JSON object, or JSON Schema output
`provider`	`string`	Optional provider routing hint
`fallbackModels`	`string[]`	Ordered fallback model identifiers
`routingStrategy`	`RoutingStrategy`	Nirmos routing policy
`metadata`	JSON object	Application metadata attached to the request

Unknown future model identifiers and routing strategies remain valid strings. This prevents model catalog additions from requiring an SDK release.

Multimodal messages

const completion = await nirmos.gateway.chat.create({
  model: "google/gemini-2.5-flash",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "Describe this diagram." },
        {
          type: "image",
          url: "https://example.com/architecture.png",
          detail: "high",
        },
      ],
    },
  ],
});

Structured output

const completion = await nirmos.gateway.chat.create({
  model: "openai/gpt-4.1-mini",
  messages: [
    { role: "user", content: "Extract the product and price: Pro, $29" },
  ],
  responseFormat: {
    type: "jsonSchema",
    name: "product",
    strict: true,
    schema: {
      type: "object",
      properties: {
        name: { type: "string" },
        price: { type: "number" },
      },
      required: ["name", "price"],
      additionalProperties: false,
    },
  },
});

const product = JSON.parse(completion.outputText);

Validate parsed output in your application even when a provider supports constrained generation.

Tool calls

const completion = await nirmos.gateway.chat.create({
  model: "anthropic/claude-sonnet-4",
  messages: [{ role: "user", content: "What is the weather in Bengaluru?" }],
  tools: [
    {
      type: "function",
      function: {
        name: "get_weather",
        description: "Get current weather for a city",
        parameters: {
          type: "object",
          properties: { city: { type: "string" } },
          required: ["city"],
        },
      },
    },
  ],
  toolChoice: "auto",
});

const calls = completion.choices[0]?.message.toolCalls ?? [];

Response

Every completion has a normalized shape:

type ChatCompletion = {
  id: string;
  createdAt: number;
  model: string;
  choices: ChatChoice[];
  outputText: string;
  usage: {
    inputTokens: number;
    outputTokens: number;
    totalTokens: number;
    cachedTokens?: number;
    reasoningTokens?: number;
  };
  metadata: {
    requestId?: string;
    traceId?: string;
    provider?: string;
    latencyMs?: number;
  };
};

Store metadata.requestId with application logs. Nirmos support and observability tools use it to locate a request.