Task Events

Async image tasks support Server-Sent Events. One SSE connection listens to all async image tasks created by the current API key, including tasks submitted after the connection opens.

This endpoint requires an image API key bound to an image batch group. General API keys do not produce async image task events.

This endpoint is intended for long-running production task dashboards or server-side schedulers. Clients should still keep the task list and task detail APIs as reconnect fallbacks.

Listen for Task Events

Interface details:

Item	Value
Method	GET
Path	/v1/images/tasks/events
Content-Type	text/event-stream
Authentication	Authorization: Bearer YOUR_API_KEY
Permission	Only tasks created by the current API key are pushed

Request example:

curl -N https://llmapi.site/v1/images/tasks/events \
  -H 'Authorization: Bearer YOUR_API_KEY'

After the connection opens, the server first sends snapshots for the current API key's active tasks in queued or running state. Historical terminal tasks in succeeded, failed, timeout, or canceled state are not sent as the initial payload; use the list or detail APIs for history.

failed and timeout are terminal events. The server does not automatically retry from these events; submit a new task if the caller wants to retry.

Event Format

The server sends standard SSE frames:

event: image_task.updated
data: {"id":"8b17fd33b0e947a08cb417e81e9ea9da","task_id":"8b17fd33b0e947a08cb417e81e9ea9da","object":"image.task","status":"running","model":"gpt-image-2","n":1}

Event types:

Event	Description
image_task.updated	Sent when a task is created, starts running, succeeds, fails, times out, or is canceled.
heartbeat comment	The server sends an SSE comment frame about every 15 seconds to keep the connection alive.

The data field is the task response object and matches GET /v1/images/tasks/{task_id}. Clients should merge updates locally by task_id.

Heartbeat frame example:

: heartbeat

Success Event Example

event: image_task.updated
data: {"id":"8b17fd33b0e947a08cb417e81e9ea9da","task_id":"8b17fd33b0e947a08cb417e81e9ea9da","object":"image.task","status":"succeeded","model":"gpt-image-2","n":1,"result":{"data":[{"index":0,"url":"https://oss.example.com/image.png","content_type":"image/png","size_bytes":1048576}]}}

Client Handling

Scenario	Recommendation
Listening to multiple tasks	Keep one /v1/images/tasks/events connection.
Submitting a new task	Do not open another SSE connection; the existing connection receives future events.
Connection drops	Reconnect SSE and call the list or detail APIs to fill any missed state.
Terminal status received	Mark that task_id as complete, but keep the SSE connection open unless no more tasks need monitoring.
Failure or timeout received	Do not wait for a server retry; submit a new task if the workflow should retry.
Server-to-server integration	Use SSE for incremental events and keep polling as a fallback.

Polling fallback:

0-60 seconds: poll every 3-5 seconds
60+ seconds: poll every 10-15 seconds
terminal status: stop polling that task