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.
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.
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 answerThe 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
| Option | Description |
|---|---|
messages | Conversation history; each message has a role (system, user, assistant, tool) and content |
model | Model to use, for example 'gpt-4o' or 'claude-sonnet-5-5'; defaults to the provider's default model |
system | System prompt (an alternative to a system message) |
temperature | Sampling temperature, 0 (deterministic) to 1 (creative) |
maxTokens | Maximum tokens to generate |
topP | Nucleus sampling |
stopSequences | Strings that stop generation |
tools / toolChoice | Tools the model may call; toolChoice is 'auto', 'none', or a specific tool name |
signal | AbortSignal that cancels the request and pending retries |
timeoutMs | Overall deadline in milliseconds across all retries |
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().
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.deltato process incremental response content.chunk.doneto determine when generation has completed.chunk.response(on the final chunk) to access the completed response, including any assembledtoolCalls.
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.
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, andmodel. A missingmessagesarray returns 400. Governance errors keep their status since 0.3.5: an exceeded budget returns 429 withAI_BUDGET_EXCEEDEDand aRetry-Afterheader, a blocked prompt returns 422 withAI_POLICY_VIOLATION. Any other provider failure returns 500 with codeAI_ERROR.aiChatStream()responds with Server-Sent Events: adeltaevent per text chunk, a finaldoneevent withcontent,finishReason,usage, andmodel, or anerrorevent if the provider fails.
Chat vs Streaming
Choose the execution model based on how your application consumes AI responses.
| API | Response model | Typical use |
|---|---|---|
ai.complete() | Complete response | Standard API requests |
ai.stream() | Incremental chunks | Interactive AI interfaces |
aiChat() | HTTP completion endpoint | Backend chat APIs |
aiChatStream() | HTTP SSE endpoint | Streaming 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.
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?