Skip to main content
This page explains how to use Server-Sent Events (SSE) endpoints in skills.video to receive generation progress updates over one long-lived HTTP response.

​
Purpose

Use SSE when your integration needs near real-time task state updates without repeated polling requests.

​
Endpoint

SSE endpoints follow the same provider and model naming as standard generation endpoints, with an /sse/ segment in the path. 
POST /api/v1/generation/sse/{provider}/{model}
Example: 
POST /api/v1/generation/sse/google/veo-3.1

​
Request parameters

The SSE request body is the same as the matching non-SSE generation endpoint, so you can reuse the same model-specific payload.

​
Path parameters

NameTypeRequiredDescription
providerstringYesModel provider slug, for example google, openai, or kling-ai.
modelstringYesModel slug under the provider, for example veo-3.1 or sora-2-pro.

​
Headers

NameRequiredDescription
Authorization: Bearer <YOUR_API_KEY>YesAPI authentication header.
Content-Type: application/jsonYesIndicates JSON request body format.
Accept: text/event-streamRecommendedExplicitly requests SSE stream responses.

​
Request body example

{
  "prompt": "sunrise over mountains in watercolor style"
}

​
Response example

A successful SSE request returns 200 OK with Content-Type: text/event-stream. The stream sends incremental status updates and ends when the task reaches a terminal state. Each data: frame is a generation object with id, status, input, data, and usage. Failed terminal frames also include sanitized code and message fields. 
data: {"id":"<GENERATION_ID>","status":"IN_QUEUE","input":{"prompt":"sunrise over mountains in watercolor style"},"data":null,"usage":{"total":0,"subscription":0,"permanent":0}}

data: {"id":"<GENERATION_ID>","status":"IN_PROGRESS","input":{"prompt":"sunrise over mountains in watercolor style"},"data":null,"usage":{"total":0,"subscription":0,"permanent":0}}

data: {"id":"<GENERATION_ID>","status":"COMPLETED","input":{"prompt":"sunrise over mountains in watercolor style"},"data":{"<OUTPUT_FIELD>":"<OUTPUT_VALUE>"},"usage":{"total":<NUMBER>,"subscription":<NUMBER>,"permanent":<NUMBER>}}
The stream ends when the task reaches a terminal status: COMPLETED, FAILED, or CANCELED. For FAILED, use code for client branching and message for a safe user-facing explanation. 
data: {"id":"<GENERATION_ID>","status":"FAILED","input":{"prompt":"sunrise over mountains in watercolor style"},"data":null,"usage":{"total":0,"subscription":0,"permanent":0},"code":"VIDEO_GENERATION_FAILED","message":"Generation failed."}

​
Error handling notes

When the request fails before the stream is established, the API returns standard JSON error responses with code and message. The legacy error field is also present for backward compatibility. Once the stream is established, handle a terminal FAILED or CANCELED frame as the generation result.
StatusMeaning
400Invalid request body or missing required fields
401Missing or invalid API key
404Provider or model route not found
422Validation error
429Rate limited
500 / 503Transient server-side error
{
  "error": "UNAUTHORIZED",
  "code": "UNAUTHORIZED",
  "message": "Unauthorized"
}

{
  "error": "VIDEO_GENERATION_INVALID_INPUT",
  "code": "VIDEO_GENERATION_INVALID_INPUT",
  "message": "'prompt' parameter is required"
}

​
Operational behavior

Design client logic for streaming workloads and transient network failure.
  • The stream closes after COMPLETED, FAILED, or CANCELED.
  • If the connection drops after you receive a generation id, reconcile with GET /api/v1/generation/{id}.
  • Retry transient HTTP 429 and 5xx responses with exponential backoff before the stream is established.

​
Retry guidance

Retrying a POST can create duplicate generation jobs if the first request was accepted but the client disconnected. Use idempotency controls if your backend provides them, or reconcile task IDs before retrying create calls.