Handle Async Task

Many operations in the Mirako API are asynchronous, especially those involving AI generation tasks like avatar building, image generation, voice cloning, and talking avatar videos. These operations return immediately with a task ID and status information, allowing you to track progress and retrieve results when complete.

Async API Endpoints

The following Mirako API endpoints use asynchronous processing:

Task Status Values

All async tasks use the same status enumeration:

Status Value	Description
`IN_QUEUE`	Task has been submitted and is waiting to be processed
`IN_PROGRESS`	Task is currently being processed
`COMPLETED`	Task finished successfully, results are available
`FAILED`	Task encountered an error and could not complete
`CANCELED`	Task was manually canceled
`TIMED_OUT`	Task exceeded the maximum processing time

Task Response Format

Whenever you send a request for an async operation, an immediate response with task information is returned:

json

{
  "data": {
    "task_id": "xdac2o3c",
    "status": "IN_QUEUE"
  }
}

The task_id is a unique identifier for tracking the operation, and the status indicates the current state of the task.

Checking Task Status

We use the status endpoint for each operation type to check progress. For example, to check for the status of avatar generation, you would use:

# Avatar generation status
GET /v1/avatar/async_generate/{task_id}/status

Successful Completion Response

When a task completes successfully, the status response includes the generated content:

json

{
  "data": {
    "task_id": "xdac2o3c",
    "status": "COMPLETED",
    "image": "iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

Failed Task Response

When a task fails, the response includes error information:

json

{
  "data": {
    "task_id": "xdac2o3c", 
    "status": "FAILED",
    "error": "Generation failed due to invalid prompt parameters"
  }
}

Webhook Notifications

For serverless-implementation, sometimes using webhook is more efficient than polling. You can provide a webhook URL to receive notifications when the task completes, instead of polling the status endpoint:

json

{
  "prompt": "A realistic photo of an Asian girl...",
  "webhook": {
    "url": "https://my-app.com/webhook/avatar-complete",
    "auth_token": "secure_token_here"
  }
}

When the task completes, Mirako will send a POST request to your webhook URL with the task results.

Best Practices

Polling: Check status every 5-10 seconds for short tasks, less frequently for longer operations
Timeouts: Implement client-side timeouts appropriate for the operation type
Webhooks: Use webhooks for better efficiency instead of continuous polling
Error Handling: Always check for FAILED status and handle errors gracefully
Task IDs: Store task IDs persistently if you need to check status across sessions