Streamable HTTP

The Streamable HTTP protocol allows you to consume AI app responses in real-time. Instead of waiting for the entire response to generate (which can take seconds for complex Generative AI tasks), this API streams the response chunks as they become available.

When to use this API

• Generative AI Experiences: When your AI app generates long-form content, streaming reduces the "Time to First Byte" perception, making the app feel faster.

• Real-time UIs: For typing indicators or "ghost text" effects similar to ChatGPT.

How it Works

This protocol utilizes Server-Sent Events (SSE). You use the exact same endpoint and authentication as the standard REST API, but you enable the stream flag in your request.

Endpoint Configuration

• URL: https://apps.nlx.ai/c/{deploymentKey}/{channelKey}-{languageCode}

• Header: nlx-api-key: YOUR_KEY

• Content-Type: application/json

Note: Ensure your URL ends with the language code (e.g., -en-US).

Enabling the Stream

Add "stream": true to the root of your JSON body.

curl -N -X POST "https://apps.nlx.ai/c/xxxx/xxxx-en-US" \
  -H "nlx-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "stream": true,
    "request": {
      "unstructured": {
        "text": "Write a short poem about coding."
      }
    }
  }'

Consuming the Stream

The server will respond with Content-Type: text/event-stream. Data is sent in chunks prefixed with data:.

JavaScript Client Example

In a browser or Node.js environment, you handle the stream by reading the response reader.

const response = await fetch('https://apps.nlx.ai/c/xxxx/xxxx-en-US', {
  method: 'POST',
  headers: {
    'nlx-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    stream: true,
    request: { unstructured: { text: "Hello" } }
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  console.log("Received chunk:", chunk);
  // Parse 'data: {...}' lines here
}