- Chat UIs that show responses as they arrive, before generation completes.
- Long-form generation (reports, code) where waiting for the full output hurts UX.
- Agent workflows that surface reasoning steps or tool calls in real time.
- Reducing perceived latency on slow models or large outputs.
Quick Start
Enable real-time response streaming for better user experience.Configuration
All models support streaming: no additional configuration needed.
Response Format
Streaming chunks:Usage in the final chunk
stream_options: { "include_usage": true } mirrors the OpenAI format and is accepted. When the stream reports token usage for the whole request, it does so in a final chunk after the content chunk, sent before the [DONE] marker.
usage from whichever chunk carries it. Most requests send it in a chunk with an empty choices array, but a request that uses server tools sends it in the chunk that also carries finish_reason, so testing every chunk for usage is the reliable approach:
Code examples
Stream Processing Patterns
The examples in this section use the Chat Completions endpoint. The same patterns apply to the Responses API: replace
chat.completions.create(...) with responses.create(...), update the endpoint to /v3/router/responses, and handle response.output_text.delta events instead of choices[0].delta.content.Basic processing
Accumulate deltas into a full string and detect completion viafinish_reason.
With error handling
Guard against network drops and unexpected errors by wrapping the stream loop in a try/except. The TypeScript example additionally resets a timeout on each chunk.Function Calling with Streaming
Stream tool calls as they’re generated:UI Integration Examples
React hook for streaming
Encapsulate streaming state in a hook so components receiveresponse and isStreaming without managing the event loop themselves.
Performance Optimization
Chunk buffering
Batching small chunks before flushing to the UI reduces render cycles and smooths perceived output.Memory management
For long completions, cap accumulation to avoid unbounded memory growth.Best Practices
Stream management
- Set reasonable timeouts (30-60 seconds).
- Implement proper error boundaries.
- Handle network interruptions gracefully.
- Provide user cancellation options.
UI/UX considerations
- Show typing indicators during streaming.
- Allow users to stop generation.
- Buffer small chunks for smoother display.
- Handle rapid updates efficiently.
Error recovery example
Troubleshooting
Stream cuts off unexpectedly- Check network stability.
- Verify timeout settings.
- Monitor for rate limiting.
- Check model-specific limits.
- Optimize chunk processing.
- Reduce buffer flush frequency.
- Check network latency.
- Consider model selection.
max_tokens implies more
than 10 minutes of generation returns 400 with type: "invalid_request_error".
Set stream: true for long outputs or reduce max_tokens.
Memory issues
- Implement chunk size limits.
- Use streaming parsers.
- Clear processed chunks.
- Monitor memory usage.
Limitations
Advanced Features
The examples in this section use the Chat Completions endpoint. The same patterns apply to the Responses API: replace
chat.completions.create(...) with responses.create(...). For cURL, use /v3/router/responses.Stream with other Gateway features
AI Gateway features like caching, timeouts, and deployment names compose directly with streaming: add them to the same request object.Parallel streaming
Fire multiple streams concurrently usingPromise.all in TypeScript and asyncio.gather in Python to get independent responses without waiting for each to finish.