Tasks API — Poll Status & Get Results

Poll generation task status and retrieve AI-generated videos and images. Real-time progress updates, error handling, and direct download URLs for all completed generations.

Poll task status and retrieve generated content.

Get Task Status

Check the status of a generation task.

GET /api/v1/tasks/{id}

Example Request

curl https://vicsee.com/api/v1/tasks/task_abc123 \
  -H "Authorization: Bearer sk-your-api-key"

Response (Processing)

{
  "success": true,
  "data": {
    "id": "task_abc123",
    "model": "seedance-2-0-text-to-video",
    "status": "processing",
    "mediaType": "video",
    "prompt": "A timelapse of a flower blooming",
    "createdAt": "2024-12-27T10:30:00.000Z",
    "result": null
  }
}

Response (Complete)

{
  "success": true,
  "data": {
    "id": "task_abc123",
    "model": "seedance-2-0-text-to-video",
    "status": "completed",
    "mediaType": "video",
    "prompt": "A timelapse of a flower blooming",
    "createdAt": "2024-12-27T10:30:00.000Z",
    "result": {
      "url": "https://cdn.vicsee.com/videos/abc123.mp4",
      "type": "video"
    }
  }
}

Response (Failed)

When a task fails, result is null and an error object describes why:

{
  "success": true,
  "data": {
    "id": "task_abc123",
    "model": "seedance-2-0-text-to-video",
    "status": "failed",
    "mediaType": "video",
    "prompt": "A timelapse of a flower blooming",
    "createdAt": "2024-12-27T10:30:00.000Z",
    "result": null,
    "error": {
      "code": "IMAGE_TOO_LARGE",
      "key": "image_too_large",
      "message": "One of your reference images is too large (max 36 megapixels). Please resize to at most 8000×4500 (16:9) or 8480×4240 (2:1) and try again."
    }
  }
}

The error field is present on every response: null on success, and always populated when status is failed (worst case { "code": "GENERATION_FAILED", "key": "generic" }).

Field	Description
`error.code`	Stable `SCREAMING_SNAKE_CASE` code for programmatic branching (e.g. `IMAGE_TOO_LARGE`, `GENERATION_FAILED`)
`error.key`	Semantic key (e.g. `image_too_large`) — branch on this if you localize
`error.message`	Human-readable English fallback you can show your end user

Status Values

Status	Description
`pending`	Task queued, not yet started
`processing`	Generation in progress
`completed`	Complete, result available
`failed`	Generation failed — see the `error` object

Polling Strategy

We recommend polling with exponential backoff:

async function waitForResult(taskId, apiKey) {
  const maxAttempts = 60;
  let delay = 1000; // Start with 1 second

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://vicsee.com/api/v1/tasks/${taskId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );

    const data = await response.json();

    if (data.data.status === 'completed') {
      return data.data.result;
    }

    if (data.data.status === 'failed') {
      throw new Error(data.data.error?.message || 'Generation failed');
    }

    await new Promise(r => setTimeout(r, delay));
    delay = Math.min(delay * 1.5, 10000); // Max 10 seconds
  }

  throw new Error('Timeout waiting for result');
}

Errors

Code	Description
`TASK_NOT_FOUND`	Task ID doesn't exist
`FORBIDDEN`	Task belongs to another user
`NO_RESULT`	Task completed but no result available

Tasks

On this page