Streaming
Server-sent events and streaming responses
Use streaming for AI responses, real-time data, and large payloads. The EEv3 API uses Server-Sent Events (SSE) to deliver incremental results as they become available.
When to Use Streaming
- AI responses— show tokens as they generate for better perceived performance
- Real-time data— live dashboards, log tailing, and event feeds
- Large payloads— process data incrementally without buffering everything in memory
SDK Streaming
Pass stream: true to any face method that supports it. The SDK returns an async iterable you can consume with for await...of.
stream.ts
const stream = await ee.ai.generate({
model: 'claude-sonnet-4-20250514',
prompt: 'Write a short story about a robot',
stream: true,
})
for await (const chunk of stream) {
process.stdout.write(chunk.text)
}
// Final result available after stream ends
console.log('\nTokens used:', stream.usage.total)SSE Format
The raw SSE stream uses standard text/event-stream format with named events for chunks, completion, and errors.
event-stream
event: chunk
data: {"text":"Once","index":0}
event: chunk
data: {"text":" upon","index":1}
event: chunk
data: {"text":" a","index":2}
event: chunk
data: {"text":" time","index":3}
event: done
data: {"usage":{"input":12,"output":487},"requestId":"req_abc123"}Client-Side: EventSource API
In the browser, use the native EventSource API to consume the stream.
client.ts
const source = new EventSource('/api/stream?prompt=Hello')
source.addEventListener('chunk', (event) => {
const data = JSON.parse(event.data)
document.getElementById('output').textContent += data.text
})
source.addEventListener('done', (event) => {
const data = JSON.parse(event.data)
console.log('Stream complete:', data.requestId)
source.close()
})
source.addEventListener('error', () => {
console.error('Stream error')
source.close()
})Server-Side: Next.js Route Handler
Proxy the stream through your own API route to keep your API key server-side. The SDK provides a toReadableStream() helper.
app/api/stream/route.ts
import { createClient } from '@evileye/sdk'
const ee = createClient({
token: process.env.EE_TOKEN!,
entity: 'my-company',
})
export async function POST(req: Request) {
const { prompt } = await req.json()
const stream = await ee.ai.generate({
model: 'claude-sonnet-4-20250514',
prompt,
stream: true,
})
return new Response(stream.toReadableStream(), {
headers: {
'Content-Type': 'text/event-stream',
'Cache-Control': 'no-cache',
Connection: 'keep-alive',
},
})
}Error Handling During Streams
Errors during a stream are delivered as an error event in the SSE stream and thrown as exceptions in the SDK iterator.
error-handling.ts
const stream = await ee.ai.generate({
prompt: 'Hello',
stream: true,
})
try {
for await (const chunk of stream) {
process.stdout.write(chunk.text)
}
} catch (err) {
// Stream errors are thrown during iteration
if (err.code === 'STREAM_INTERRUPTED') {
console.error('Stream was interrupted:', err.message)
// Optionally restart from last known position
}
}Related
- API Reference— which faces and methods support streaming
- Error Handling— error codes and recovery strategies