Query Task Status

Check the status of a content generation task.

Endpoint

GET /api/tasks/:id

Authentication

All requests require Bearer Token authentication:

Authorization: Bearer YOUR_API_KEY

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The unique task ID returned when creating the task

Examples

cURL

curl -X GET https://api.firebirdgen.com/api/tasks/task_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Python

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.firebirdgen.com'

def query_task(task_id):
    headers = {
        'Authorization': f'Bearer {API_KEY}'
    }
    
    response = requests.get(
        f'{BASE_URL}/api/tasks/{task_id}',
        headers=headers
    )
    response.raise_for_status()
    
    result = response.json()
    return result['data']

task = query_task('task_abc123')
print(f"Status: {task['status']}")

if task['status'] == 'success':
    print(f"Video URL: {task['resultUrl']}")

JavaScript

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.firebirdgen.com';

async function queryTask(taskId) {
  const response = await fetch(`${BASE_URL}/api/tasks/${taskId}`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });

  const result = await response.json();
  return result.data;
}

queryTask('task_abc123').then(task => {
  console.log('Status:', task.status);
  
  if (task.status === 'success') {
    console.log('Video URL:', task.resultUrl);
  }
});

Response

Text-to-Video Response

{
  "success": true,
  "statusCode": 200,
  "data": {
    "taskId": "task_abc123",
    "status": "success",
    "resultUrl": "https://cdn.heo365.com/sora2/video.mp4",
    "createdAt": "2024-10-23T10:00:00Z",
    "completedAt": "2024-10-23T10:03:00Z",
    "requestParams": {
      "projectName": "sora2",
      "modelName": "sora2_text_to_video",
      "prompt": "A beautiful sunset over the ocean",
      "imageUrl": "",
      "aspectRatio": "9:16",
      "duration": 10,
      "callbackUrl": "https://your-domain.com/webhook",
      "remixTargetId": ""
    }
  }
}

Image-to-Video Response

{
  "success": true,
  "statusCode": 200,
  "data": {
    "taskId": "task_abc123",
    "status": "success",
    "resultUrl": "https://cdn.heo365.com/sora2/video.mp4",
    "createdAt": "2024-10-23T10:00:00Z",
    "completedAt": "2024-10-23T10:03:00Z",
    "requestParams": {
      "projectName": "sora2",
      "modelName": "sora2_image_to_video",
      "prompt": "Animate this image with gentle camera movement",
      "imageUrl": "https://example.com/image.jpg",
      "aspectRatio": "9:16",
      "duration": 10,
      "callbackUrl": "https://your-domain.com/webhook",
      "remixTargetId": ""
    }
  }
}

Response Fields

Field	Type	Description
success	boolean	Whether the request was successful
statusCode	number	HTTP status code
data.taskId	string	Unique identifier for the task
data.status	string	Task status: processing, success, failed
data.errorMessage	string	Error description (only when status is failed)
data.resultUrl	string | null	CDN URL of the generated video, null if not available
data.createdAt	string	ISO 8601 timestamp when task was created
data.completedAt	string | null	ISO 8601 timestamp when task completed, null if still processing
data.requestParams	object	Original parameters used to create the task
data.requestParams.projectName	string	Project name (sora2)
data.requestParams.modelName	string	Model used for generation
data.requestParams.prompt	string	Video description prompt
data.requestParams.imageUrl	string	Image URL for image-to-video, empty string for text-to-video
data.requestParams.aspectRatio	string	Video aspect ratio (9:16 or 16:9, default: 9:16)
data.requestParams.duration	number	Video duration in seconds
data.requestParams.remixTargetId	string	Previous task ID if this is a remix
data.requestParams.callbackUrl	string	Webhook URL (if provided)
data.requestParams.remixTargetId	string	Original task ID if this is a remix (optional)

Field Notes

• errorMessage: Only present when status is failed
• resultUrl: null when task is processing or failed
• completedAt: null when task is still processing
• imageUrl: Empty string "" for text-to-video tasks
• remixTargetId: Only present if the task was created as a remix of another task

Task Status Values

Status	Description
processing	Task is being processed (typically 3-5 minutes)
success	Task completed successfully, video is ready
failed	Task failed, please try again

Status Codes

Code	Description
200	Success - Task found and returned
404	Not Found - Task does not exist or you don't have access
401	Unauthorized - Invalid or missing API key
429	Too Many Requests - Rate limit exceeded

Error Response

Task Not Found

{
  "success": false,
  "statusCode": 404,
  "error": {
    "code": "TASK_NOT_FOUND",
    "message": "Task not found or you don't have access to this task"
  }
}

Rate Limit Exceeded

{
  "success": false,
  "statusCode": 429,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests, please try again later"
  }
}

Failed Task Response

{
  "success": true,
  "statusCode": 200,
  "data": {
    "taskId": "task_abc123",
    "status": "failed",
    "errorMessage": "Failed to generate, system error please try again",
    "resultUrl": null,
    "createdAt": "2024-10-23T10:00:00Z",
    "completedAt": "2024-10-23T10:05:00Z",
    "requestParams": {
      "projectName": "sora2",
      "modelName": "sora2_text_to_video",
      "prompt": "Invalid prompt content",
      "imageUrl": "",
      "aspectRatio": "9:16",
      "duration": 10,
      "callbackUrl": "https://your-domain.com/webhook"
    }
  }
}

Notes

Polling Interval

When polling for task status, we recommend checking every 10-15 seconds. Most tasks complete within 3-5 minutes.

Rate Limits

• All users: 10 requests per second

Usage Example

Complete Workflow

Python

import requests
import time

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.firebirdgen.com'

def create_and_wait_for_task():
    # Step 1: Create task
    headers = {
        'Authorization': f'Bearer {API_KEY}',
        'Content-Type': 'application/json'
    }
    
    create_response = requests.post(
        f'{BASE_URL}/api/tasks',
        headers=headers,
        json={
            'requestParams': {
                'projectName': 'sora2',
                'modelName': 'sora2_text_to_video',
                'prompt': 'A beautiful sunset over the ocean',
                'aspectRatio': '9:16',
                'duration': 10
            }
        }
    )
    
    task_id = create_response.json()['data']['taskId']
    print(f'Task created: {task_id}')
    
    # Step 2: Poll for completion
    while True:
        response = requests.get(
            f'{BASE_URL}/api/tasks/{task_id}',
            headers=headers
        )
        
        task = response.json()['data']
        status = task['status']
        
        print(f'Status: {status}')
        
        if status == 'success':
            print(f'Video ready: {task["resultUrl"]}')
            return task
        elif status == 'failed':
            print(f'Task failed: {task.get("errorMessage")}')
            return None
        
        # Wait 10 seconds before next check
        time.sleep(10)

result = create_and_wait_for_task()

JavaScript

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.firebirdgen.com';

async function createAndWaitForTask() {
  // Step 1: Create task
  const createResponse = await fetch(`${BASE_URL}/api/tasks`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      requestParams: {
        projectName: 'sora2',
        modelName: 'sora2_text_to_video',
        prompt: 'A beautiful sunset over the ocean',
        aspectRatio: '9:16',
        duration: 10
      }
    })
  });

  const createData = await createResponse.json();
  const taskId = createData.data.taskId;
  console.log('Task created:', taskId);

  // Step 2: Poll for completion
  while (true) {
    const response = await fetch(`${BASE_URL}/api/tasks/${taskId}`, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`
      }
    });

    const data = await response.json();
    const task = data.data;
    const status = task.status;

    console.log('Status:', status);

    if (status === 'success') {
      console.log('Video ready:', task.resultUrl);
      return task;
    } else if (status === 'failed') {
      console.log('Task failed:', task.errorMessage);
      return null;
    }

    // Wait 10 seconds before next check
    await new Promise(resolve => setTimeout(resolve, 10000));
  }
}

createAndWaitForTask();

Next Steps

• Create Task - Learn how to create video generation tasks
• Use webhooks for automatic notifications instead of polling (coming soon)