Understanding Async Task Processing in GlobalAI OPC

Video and image generation are compute-intensive operations that can take anywhere from a few seconds to several minutes to complete. Rather than making you wait for a synchronous HTTP response that could time out, GlobalAI OPC uses an asynchronous task model: you submit a generation request, receive a task ID immediately, and then poll a separate endpoint to check progress until your result is ready.

How Async Tasks Work

Create a task

Send a POST request to the appropriate generation endpoint (for example, /v1/sora/videos for Sora video generation). The API responds immediately with a task id and an initial status of queued. Keep this ID — you’ll need it to retrieve your result.

Poll for status

Send a GET request to /v1/result/{id} using the task ID you received. Repeat this request on a regular interval (every 30–60 seconds for video, every 2–5 seconds for images) until the status changes from queued or processing to a terminal state.

Retrieve your result

When the status field returns completed, the response includes a result URL (for example, video_url or image_url) containing your generated media. Download or store this URL promptly — result URLs expire after 24 hours.

Task Statuses

Every task returned by the API carries a status field. The following table describes each possible value:

Status	Description
`queued`	The task is waiting in the queue and has not yet started processing.
`processing`	The task is actively being generated. Continue polling.
`completed`	Generation is complete. The result URL is available in the response.
`failed`	Generation failed. Inspect the `error` field in the response for details.
`cancelled`	The task was cancelled before completion. Applies to Seedance 1.5 tasks.

Polling Best Practices

Poll every 30–60 seconds for video generation to avoid unnecessary API calls while respecting server load.
Poll every 2–5 seconds for image generation, which typically completes much faster than video.
Stop polling immediately when the status is completed, failed, or cancelled — further polling is wasteful and unnecessary.
Video URLs expire after 24 hours — download your generated video to your own storage as soon as generation completes.
Image URLs also expire after 24 hours — save generated images to your own storage rather than relying on the temporary URL long-term.
Do not retry on failed status without reviewing the error field first; the same prompt or parameters may continue to fail.

Code Example: Full Polling Loop

The example below creates a video generation task using the Sora model, then polls in a loop until the task completes or fails.

import requests
import time

API_KEY = "your_api_key"
BASE_URL = "https://zcbservice.aizfw.cn/kyyReactApiServer"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Create task
response = requests.post(
    f"{BASE_URL}/v1/sora/videos",
    headers=HEADERS,
    json={
        "model": "openAiSora2Plus",
        "prompt": "A cat dancing in the rain, cinematic style",
        "aspect_ratio": "16:9",
        "seconds": 8
    }
)
task_id = response.json()["id"]
print(f"Task created: {task_id}")

# Poll for result
while True:
    result = requests.get(f"{BASE_URL}/v1/result/{task_id}", headers=HEADERS).json()
    status = result["status"]
    print(f"Status: {status}")
    if status == "completed":
        print(f"Video URL: {result['video_url']}")
        break
    elif status == "failed":
        print(f"Failed: {result['error']}")
        break
    elif status == "cancelled":
        print("Task was cancelled.")
        break
    time.sleep(30)

# Step 1: Create a video generation task
curl -X POST https://zcbservice.aizfw.cn/kyyReactApiServer/v1/sora/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openAiSora2Plus",
    "prompt": "A cat dancing in the rain, cinematic style",
    "aspect_ratio": "16:9",
    "seconds": 8
  }'

# The response contains your task ID, e.g.:
# { "id": "task_abc123", "status": "queued" }

# Step 2: Poll for the result using the task ID
# Replace TASK_ID with the id value from the response above
curl -X GET https://zcbservice.aizfw.cn/kyyReactApiServer/v1/result/TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

# Keep repeating the GET request every 30–60 seconds until
# the status field returns "completed" or "failed".
# On completion, the response will include a "video_url" field.

Result URLs (both video and image) expire 24 hours after generation completes. Download and store your generated media in your own storage immediately after retrieval — you cannot regenerate an expired URL without re-running the full generation task.

Text chat APIs (OpenAI Chat, Claude Messages, and Gemini Native) are synchronous — they return the model’s response directly in the HTTP response body and do not use the async task pattern described on this page.

Getting Started

Core Concepts

Changelog

Understanding Async Task Processing in GlobalAI OPC

How Async Tasks Work

Task Statuses

Polling Best Practices

Code Example: Full Polling Loop

​How Async Tasks Work

​Task Statuses

​Polling Best Practices

​Code Example: Full Polling Loop

How Async Tasks Work

Task Statuses

Polling Best Practices

Code Example: Full Polling Loop