Tasks

Check generation status and download results

Poll task status and download 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": "sora-2",
    "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": "sora-2",
    "status": "success",
    "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"
    }
  }
}

Status Values

StatusDescription
pendingTask queued, not yet started
processingGeneration in progress
successComplete, result available
failedGeneration failed

Download Content

Get the download URL or stream the content directly.

GET /api/v1/tasks/{id}/download

Example Request

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

Response

{
  "success": true,
  "data": {
    "url": "https://cdn.vicsee.com/videos/abc123.mp4",
    "type": "video",
    "expiresAt": null
  }
}

Proxy Mode

To stream content directly through the API (useful for avoiding CORS):

curl "https://vicsee.com/api/v1/tasks/task_abc123/download?mode=proxy" \
  -H "Authorization: Bearer sk-your-api-key" \
  -o output.mp4

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 === 'success') {
      return data.data.result;
    }

    if (data.data.status === 'failed') {
      throw new Error('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

CodeDescription
TASK_NOT_FOUNDTask ID doesn't exist
FORBIDDENTask belongs to another user
TASK_NOT_COMPLETETried to download before completion
NO_RESULTTask completed but no result available