AI Platform

Chat Completions and Streaming

Use AxilJS for AI chat completions, streaming responses, system instructions, cancellation, and HTTP chat endpoints with SSE in TypeScript and Node.js.

5 min readUpdated DocumentationEdit this page
On this page7

AxilJS provides APIs for building AI chat applications in TypeScript and Node.js, including standard chat completions, streamed AI responses, system instructions, and HTTP endpoints.

Use ai.complete() when you need the complete response at once, or ai.stream() when your application needs to process the AI response incrementally.

Chat Completions

Use ai.complete() to send a conversation to an AI provider and wait for the complete response.

TypeScript
TS
1const res = await ai.complete({
2  messages: [
3    {
4      role: 'user',
5      content: 'Hello!'
6    }
7  ],
8  system: 'You are helpful.',
9  temperature: 0.7
10})
11
12res.content       // generated text
13res.finishReason  // 'stop' | 'tool_use' | 'length' | 'error'
14res.usage         // { promptTokens, completionTokens, totalTokens }
15res.model         // model that produced the answer

The messages array contains the conversation history, while system provides instructions that guide the AI's behavior. The temperature option controls the variability of generated responses.

This approach is suitable for APIs and applications where the client can wait for the complete AI response before displaying or processing it.

Completion Options

OptionDescription
messagesConversation history; each message has a role (system, user, assistant, tool) and content
modelModel to use, for example 'gpt-4o' or 'claude-sonnet-5-5'; defaults to the provider's default model
systemSystem prompt (an alternative to a system message)
temperatureSampling temperature, 0 (deterministic) to 1 (creative)
maxTokensMaximum tokens to generate
topPNucleus sampling
stopSequencesStrings that stop generation
tools / toolChoiceTools the model may call; toolChoice is 'auto', 'none', or a specific tool name
signalAbortSignal that cancels the request and pending retries
timeoutMsOverall deadline in milliseconds across all retries
TypeScript
TS
1const res = await ai.complete({
2  model: 'claude-opus-5-5',
3  messages: [{ role: 'user', content: 'Summarize this release in one line.' }],
4  maxTokens: 200,
5  timeoutMs: 15_000
6})

Streaming AI Responses

For interactive applications, AxilJS supports streaming responses through ai.stream().

TypeScript
TS
1for await (const chunk of ai.stream({ messages })) {
2  if (chunk.delta) process.stdout.write(chunk.delta)
3
4  if (chunk.done) console.log(chunk.response)
5}

The async iterator yields response chunks as the AI generates them.

You can use:

  • chunk.delta to process incremental response content.
  • chunk.done to determine when generation has completed.
  • chunk.response (on the final chunk) to access the completed response, including any assembled toolCalls.

When tools are used while streaming, tool calls arrive as chunks with toolCallDelta and toolCallIndex (plus toolCallArgumentsDelta JSON fragments for OpenAI and Anthropic). The final chunk's response.toolCalls holds the assembled, parsed calls.

Streaming is particularly useful for AI chat interfaces because users can see generated content progressively instead of waiting for the entire completion.

HTTP Chat Endpoints

AxilJS also provides route handlers for exposing AI chat functionality through your application API.

TypeScript
TS
1import { aiChat, aiChatStream } from '@axiljs/ai'
2
3app.post('/chat', aiChat({ provider: ai }))
4
5app.post(
6  '/chat/stream',
7  aiChatStream({
8    provider: ai,
9    model: 'claude-sonnet-5-5',
10    system: 'You are a helpful assistant.'
11  })
12)

Both handlers accept these options: provider (required), model, system, temperature, and maxTokens.

The request body must include a messages array. It may also set model, system, and temperature (and maxTokens for aiChat()), which take precedence over the handler options.

  • aiChat() responds with JSON: content, finishReason, usage, and model. A missing messages array returns 400. Governance errors keep their status since 0.3.5: an exceeded budget returns 429 with AI_BUDGET_EXCEEDED and a Retry-After header, a blocked prompt returns 422 with AI_POLICY_VIOLATION. Any other provider failure returns 500 with code AI_ERROR.
  • aiChatStream() responds with Server-Sent Events: a delta event per text chunk, a final done event with content, finishReason, usage, and model, or an error event if the provider fails.

Chat vs Streaming

Choose the execution model based on how your application consumes AI responses.

APIResponse modelTypical use
ai.complete()Complete responseStandard API requests
ai.stream()Incremental chunksInteractive AI interfaces
aiChat()HTTP completion endpointBackend chat APIs
aiChatStream()HTTP SSE endpointStreaming chat APIs

Typical AI Chat Architecture

A common AxilJS implementation connects an HTTP endpoint to an AI provider and returns either a complete or streamed response.

Client
AxilJS HTTP Endpoint
aiChat()
Complete Response
aiChatStream()
SSE events (delta … done)
Client

When to Use Streaming

Use streaming when response latency and user experience are important. It is a good fit for:

  • AI chat interfaces
  • Real-time AI assistants
  • Long-form AI generation
  • Interactive developer tools
  • Applications that display tokens or response chunks progressively

For simpler backend operations where the complete result is required before continuing, ai.complete() provides a more straightforward execution model.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY