Chat completions

Chat completions are available through both client libraries. Use a provider-qualified model to make direct resolution explicit.

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

console.log(completion.outputText);

const completion = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [
    { role: "system", content: "You are a concise technical editor." },
    { role: "user", content: "Rewrite: caching got better" },
  ],
  temperature: 0.2,
  max_tokens: 300,
});

console.log(completion.choices[0]?.message.content);

Choose a target

Nirmos SDK calls require exactly one of model or route:

// Direct model
await nirmos.gateway.chat.create({
  model: "openai/gpt-5.4-mini",
  messages,
});

// Centrally configured route
await nirmos.gateway.chat.create({
  route: "production-chat",
  messages,
});

OpenAI-compatible clients call the same route through model: "nirmos/production-chat". See Routing and fallback.

Nirmos SDK request fields

Field	Type	Purpose
`model`	`string`	Physical model or `nirmos/<route-slug>`; exclusive with `route`
`route`	`string`	Active route ID or slug; exclusive with `model`
`messages`	`ChatMessage[]`	Conversation messages
`prompt`	`PromptReference`	Managed prompt rendered by the SDK before the request
`temperature`	`number`	Sampling temperature
`topP`	`number`	Nucleus sampling threshold
`maxOutputTokens`	`number`	Maximum generated tokens
`stop`	`string \| string[]`	Stop sequence or sequences
`tools`	`FunctionTool[]`	Function tool definitions
`toolChoice`	`ToolChoice`	Tool selection behavior
`responseFormat`	`ResponseFormat`	Text, JSON object, or JSON Schema output
`provider`	`string`	Optional provider hint for direct model resolution
`fallbackModels`	`string[]`	Ordered direct-model fallbacks
`routingStrategy`	`RoutingStrategy`	Routing hint forwarded to the gateway
`metadata`	JSON object	Optional application metadata sent in the gateway request

Multimodal content

The Nirmos SDK uses normalized content-part names and maps them to the OpenAI wire shape.

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

await client.chat.completions.create({
  model: "google/gemini-3.5-flash",
  messages: [{
    role: "user",
    content: [
      { type: "text", text: "Describe this diagram." },
      { type: "image_url", image_url: { url: "https://example.com/diagram.png", detail: "high" } },
    ],
  }],
});

The selected model must advertise the required vision capability.

Structured output

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

const completion = await client.chat.completions.create({
  model: "openai/gpt-5.4-mini",
  messages: [{ role: "user", content: "Extract: Pro costs $29" }],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "product",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          price: { type: "number" },
        },
        required: ["name", "price"],
        additionalProperties: false,
      },
    },
  },
});

Validate parsed output in your application before using it for writes or tool execution.

Normalized response

chat.create returns choices, joined outputText, normalized token usage, and optional request metadata:

console.log({
  text: completion.outputText,
  inputTokens: completion.usage.inputTokens,
  outputTokens: completion.usage.outputTokens,
  requestId: completion.metadata.requestId,
  provider: completion.metadata.provider,
});