OSS supports two response modes for data streaming: traditional HTTP mode returns a single response packet per request, while server-sent events (SSE) mode pushes multiple events from the server to the client as data becomes available. SSE is well-suited for real-time update scenarios such as dynamic text generation.
Traditional HTTP mode
Each request returns a single response packet. The response body is a JSON object delivered all at once after the server finishes processing.
Sample response:
HTTP/1.1 200 OK
Server: AliyunOSS
Date: Mon, 07 Aug 2023 09:44:02 GMT
Content-Type: application/json;charset=UTF-8
Connection: close
Vary: Accept-Encoding
x-oss-request-id: 64D0BCDD88339E32330E2D1D
x-oss-server-time: 5865
Content-Encoding: gzip
{
"RequestID": "64D0BCDD88339E32330E2D1D",
"Output": {
"Text": "A Ghost, the Communist Ghost, haunts the European continent...",
"FinishReason": "stop"
}
}SSE mode
SSE is unidirectional — the server pushes data to the client, not the other way around. The EventSource interface in the HTML Living Standard (formerly known as HTML5) provides native browser support for consuming SSE streams.
Event stream format
The event stream is plain text encoded in UTF-8. Individual events are separated by two newline characters (\n\n). Each event consists of one or more key-value pair lines in the format [key]: value\n.
The response header Content-Type: text/event-stream;charset=UTF-8 identifies an SSE response. OSS also uses Transfer-Encoding: chunked to deliver the stream.
The valid keys are:
| Key | Description |
|---|---|
id | The event ID. The client uses this to track the last received event and resume from where it left off if the connection is interrupted. |
event | The event type. Use addEventListener() on the client to listen for specific event types. If omitted, the default onmessage handler fires. |
data | The event payload. For OSS streaming responses, the value is a JSON object containing the response parameters. |
Sample response
HTTP/1.1 200 OK
Server: AliyunOSS
Date: Mon, 07 Aug 2023 09:44:36 GMT
Content-Type: text/event-stream;charset=UTF-8
Transfer-Encoding: chunked
Connection: close
x-oss-request-id: 64D0BD0388339E30331D2D1D
x-oss-server-time: 761
id: 0
event: message
data: {"RequestId":"","Output":{"Text":"A Ghost,","FinishReason":"null"},"Usage":{"InputTokens":320,"OutputTokens":3}}
id: 1
event: message
data: {"RequestId":"","Output":{"Text":"A Ghost, the Communist Ghost, haunts the European","FinishReason":"null"},"Usage":{"InputTokens":320,"OutputTokens":11}}
id: 2
event: message
data: {"RequestId":"","Output":{"Text":"A Ghost, the Communist Ghost, haunts the European continent. In order to holy suppression of","FinishReason":"null"},"Usage":{"InputTokens":320,"OutputTokens":19}}
......
id: 27
event: Result
data: {"RequestId":"","Output":{"Text":"A Ghost, the Communist Ghost, haunts the European continent. In order to holy suppression of this ghost, all forces of the old Europe, including the Pope and the Czar, Metternich and Guizot, the radical party in France and the police in Germany, have united. Is there any opposition party that is not denounced by its governing enemies as a Communist? And is there any opposition party that does not use the charge of Communism as a weapon against more progressive oppositionists and its reactionary enemies? From this fact we can draw two conclusions: Communism has been recognized by all the forces of Europe as a power; it is now the turn of the Communists to make themselves known to the world, to state their views, their aims, their intentions, and to publish their own manifestos in order to refute the myth about the Communist ghost. For this purpose, delegates of the Communist parties of all countries assembled in London and adopted the following manifesto, which is published in English, French, German, Italian, Flemish and Danish.","FinishReason":"stop"},"Usage":{"InputTokens":320,"OutputTokens":212}}Each message contains incremental data, indicating that the data is progressively enriched or modified as part of each request. The final event uses event: Result and sets FinishReason to stop.
Response data fields
The data field in each event is a JSON object with the following fields:
| Field | Description |
|---|---|
RequestId | The request ID. |
Output.Text | The generated text, incrementally updated across events. |
Output.FinishReason | null while streaming; stop on the final event. |
Usage.InputTokens | The number of input tokens consumed. |
Usage.OutputTokens | The number of output tokens generated so far. |
Consume the stream on the client
Use the EventSource interface to receive events in a browser environment. For server-side or non-browser clients, parse the fetch response body as a readable stream and split on \n\n to extract individual events.
SSE requires the server to keep the connection open for the duration of the stream. Some intermediate proxies close idle HTTP connections after a short timeout. If you observe premature stream termination, configure your proxy or load balancer to support long-lived connections.