Video task workflow

PopGo video generation is asynchronous. Submit a task, keep its ID, poll the task, and download the result after completion.

Endpoints

POST https://api.popgo.site/v1/videos
GET  https://api.popgo.site/v1/videos/{task_id}
GET  https://api.popgo.site/v1/videos/{task_id}/content
Authorization: Bearer YOUR_API_KEY

Clients use these public paths regardless of the selected channel.

Common fields

Field	Type	Description
model	string	Required public model ID
prompt	string	Required scene, motion, camera, and audio instruction
duration / seconds	integer	Only values allowed by the selected model
resolution	string	Model-specific value such as 480p, 720p, 1080p, or 4K
aspect_ratio	string	Model-specific aspect ratio
Reference fields	array / string	Image, video, or audio fields listed by the model page

curl -X POST https://api.popgo.site/v1/videos \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "prompt": "A bamboo forest in morning mist, slow forward camera movement",
    "seconds": 5,
    "resolution": "480p",
    "aspect_ratio": "16:9"
  }'

Save the returned ID, for example {"id":"YOUR_TASK_ID","status":"queued"}.

Polling and progress

curl https://api.popgo.site/v1/videos/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Status	Meaning	Action
queued	Waiting to run	Poll after a delay
in_progress	Generating	Show progress when present and poll again
completed	Ready	Read the URL or download /content
failed	Failed	Read the error before deciding whether to retry

Some models return a numeric progress; others return only a status. Do not invent a percentage when the field is absent.

Completion and errors

curl -L https://api.popgo.site/v1/videos/YOUR_TASK_ID/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o output.mp4

HTTP 400 usually indicates an invalid model, type, duration, resolution, ratio, or reference. HTTP 401/403 indicates authentication or access. A query 400 should be checked against the PopGo task ID and /v1/videos/{task_id} path. Video billing can be per task, per second, or per specification; use the model page rather than polling count.

Polling, timeouts and retry boundaries

Send creation once and immediately retain id, model, duration, resolution and material mode. A create timeout may occur after acceptance: inspect task records before resubmitting. Polling and download retries against the same id do not create a second video.

Use 3–5s in general, 10–15s for C and about10s for Kling with at least15 minutes allowed. Apply bounded backoff to429/502/503 or transient network failures, respecting Retry-After. Fix parameters before retrying400; fix credentials/permissions for401/403. At the client deadline, show a wait timeout and retain the task for later polling, without labeling it a service failure.

progress can stay0 until100 or be absent. model,usage,resolution,actual duration and fps may also be absent. Keep submitted parameters and inspect downloaded media; missing usage does not mean free. queued/in_progress are not failures; completed starts download.

Result URLs can expire or require authentication. Prefer PopGo /content. After completed, retry temporarily unavailable content within a limit instead of creating again. Allow sufficient download time and verify video content rather than a JSON error page. Never send a PopGo API Key to an external media host.

Separate five diagnostic stages

Stage	What it establishes	What it does not establish
UI validation	Local mode, count and source acceptance	No request does not mean service rejection
PopGo parsing and capability validation	Whether400/500 occurred before task creation	Missing service logs do not automatically prove a provider fault
Outgoing payload	Image/video/audio fields and roles	Correct fields do not guarantee media access
Task acceptance and polling	ID, status and failure stage	200 or ID does not prove reference use or zero cost
Final media	Reference effect on frames, subject, action and sound	A download URL does not prove quality

Record sanitized model, time, placeholder task ID, mode, reference counts/sources and short errors. Exclude keys,cookies,signed URLs and private materials. Distinguish capacity from moderation; even failed jobs require billing review. Correct known causes before incurring a new generation cost.