openrouter-streaming-setup

name	openrouter-streaming-setup
description	Implement streaming responses with OpenRouter for real-time UIs. Use when building chat interfaces, reducing time-to-first-token, or processing long completions. Triggers: 'openrouter streaming', 'openrouter sse', 'stream response openrouter', 'real-time openrouter'.
allowed-tools	Read, Write, Edit, Grep, Bash(python3:*), Bash(node:*)
version	1.20.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","openrouter","streaming","real-time"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

OpenRouter Streaming Setup

Overview

OpenRouter supports Server-Sent Events (SSE) streaming via stream: true, compatible with the OpenAI SDK. Streaming returns tokens as they're generated, reducing time-to-first-token (TTFT) from seconds to milliseconds. Usage stats are available via stream_options: {include_usage: true} in the final chunk. This skill covers Python and TypeScript streaming, SSE forwarding to browsers, and error recovery.

Prerequisites

• An OpenRouter API key (sk-or-v1-...) exported as OPENROUTER_API_KEY — see the openrouter-install-auth skill for setup
• Python 3.8+ or Node.js 18+ with the OpenAI SDK (the async example uses AsyncOpenAI from the same Python package)
• FastAPI if you plan to forward the SSE stream to browsers per the SSE Forwarding section
• A streaming-appropriate client timeout (e.g. 120s) — longer than for non-streaming requests

Instructions

1. Start with Python: Basic Streaming — pass stream=True plus stream_options={"include_usage": True} so the final chunk carries token counts, and print each chunk.choices[0].delta.content as it arrives.
2. Wrap that loop in the Python: Streaming with Metrics generator to capture TTFT and total time per request; the metrics dict is available after the generator is exhausted.
3. For Node services, use the TypeScript: Streaming for await loop over the same stream: true request.
4. To reach a browser UI, expose the FastAPI endpoint in SSE Forwarding to Browser — it re-emits each token as a data: {"token": ...} SSE line and terminates with data: [DONE].
5. Consume that endpoint with the Browser Client (JavaScript) reader loop, appending tokens to the DOM as they decode.
6. In async web frameworks, switch to the Async Streaming pattern built on AsyncOpenAI.
7. Handle mid-stream failures (cut-offs, missing usage, keep-alive pings, finish_reason: "length") per the Error Handling table.

Python: Basic Streaming

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
    default_headers={: , : },
)


stream = client.chat.completions.create(
    model=,
    messages=[{: , : }],
    max_tokens=,
    stream=,
    stream_options={: },  
)

full_content = []
 chunk  stream:
     chunk.choices  chunk.choices[].delta.content:
        token = chunk.choices[].delta.content
        (token, end=, flush=)
        full_content.append(token)

    
     chunk.usage:
        ()

result = .join(full_content)