Create Asynchronous Voice Cloning Task

The create task endpoint allows you to submit long text content for voice cloning processing. This endpoint is ideal for text content longer than 1000 characters where processing may take some time.

Endpoint


POST https://aivoiceclonefree.com/api/async-clone/create-task

Authentication

This endpoint requires authentication using your API key in the Authorization header:


Authorization: Bearer YOUR_API_KEY

Request Parameters

Required Parameters

Parameter	Type	Description
`audio_file`	File	The audio sample file for voice cloning (WAV, MP3, M4A formats)
`text`	String	The text to be converted to speech using the cloned voice

Optional Parameters

Parameter	Type	Default	Description
`speed`	Float	1.0	Speech speed (0.5 - 2.0)
`pitch`	Float	0.0	Pitch adjustment (-1.0 to 1.0)
`callback_url`	String	null	URL to receive webhook notifications when task completes

Audio File Requirements

Formats: WAV, MP3, M4A
Duration: 5-30 seconds
Quality: Clear audio with minimal background noise
File Size: Maximum 4.5MB
Content: Natural speech in the target voice

Request Example

cURL


curl -X POST "https://aivoiceclonefree.com/api/async-clone/create-task" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "audio_file=@voice_sample.wav" \
  -F "text=This is a very long text that will be processed asynchronously because it exceeds the character limit for synchronous processing..." \
  -F "speed=1.1" \
  -F "pitch=0.0" \
  -F "callback_url=https://your-domain.com/webhook"

Python


import requests
 
url = "https://aivoiceclonefree.com/api/async-clone/create-task"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}
 
with open("voice_sample.wav", "rb") as audio_file:
    files = {
        "audio_file": audio_file
    }
    data = {
        "text": "This is a very long text that will be processed asynchronously...",
        "speed": 1.1,
        "pitch": 0.0,
        "callback_url": "https://your-domain.com/webhook"
    }
    
    response = requests.post(url, headers=headers, files=files, data=data)
    result = response.json()
    task_id = result["task_id"]

JavaScript


const formData = new FormData();
formData.append('audio_file', audioFile);
formData.append('text', 'This is a very long text that will be processed asynchronously...');
formData.append('speed', '1.1');
formData.append('pitch', '0.0');
formData.append('callback_url', 'https://your-domain.com/webhook');
 
fetch('https://aivoiceclonefree.com/api/async-clone/create-task', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: formData
})
.then(response => response.json())
.then(data => {
  const taskId = data.task_id;
  console.log('Task created:', taskId);
});

Response

Success Response (202 Accepted)


{
  "task_id": "abc123def456ghi789",
  "status": "pending",
  "estimated_completion": "2024-01-15T10:30:00Z",
  "created_at": "2024-01-15T10:25:00Z"
}

Response Fields

Field	Type	Description
`task_id`	String	Unique identifier for the task
`status`	String	Current task status (`pending`)
`estimated_completion`	String	Estimated completion time (ISO 8601 format)
`created_at`	String	Task creation timestamp (ISO 8601 format)

Error Responses

400 Bad Request


{
  "detail": "Invalid audio file format. Supported formats: WAV, MP3, M4A"
}

401 Unauthorized


{
  "detail": "Invalid or missing API key"
}

403 Forbidden


{
  "detail": "Professional or Unlimited subscription required"
}

413 Payload Too Large


{
  "detail": "Audio file too large. Maximum size: 4.5MB"
}

422 Unprocessable Entity


{
  "detail": "Text too short for async processing. Use sync endpoint for texts under 1000 characters"
}

429 Too Many Requests


{
  "detail": "Too many active tasks. Please wait for current tasks to complete"
}

500 Internal Server Error


{
  "detail": "Internal server error. Please try again later"
}

Webhook Notifications

If you provide a callback_url, the system will send HTTP POST notifications when the task status changes:

Task Completion Webhook


{
  "task_id": "abc123def456ghi789",
  "status": "completed",
  "result_url": "https://aivoiceclonefree.com/api/async-clone/task-result/abc123def456ghi789",
  "completed_at": "2024-01-15T10:32:00Z"
}

Task Failure Webhook


{
  "task_id": "abc123def456ghi789",
  "status": "failed",
  "error": "Processing failed due to audio quality issues",
  "failed_at": "2024-01-15T10:31:00Z"
}

Usage Limits

Text Length: Minimum 1000 characters, maximum varies by plan
Audio Duration: 5-30 seconds
File Size: Maximum 4.5MB
Concurrent Tasks: Varies by subscription plan
Processing Time: Typically 2-10 minutes depending on text length

Next Steps

After creating a task, you’ll need to:

Monitor Progress: Use the Task Status endpoint to check progress
Download Result: Use the Task Result endpoint to get the generated audio

Best Practices

Store Task ID: Save the returned task_id for status checking and result retrieval
Implement Webhooks: Use callback URLs for real-time status updates
Error Handling: Implement proper error handling and retry logic
Polling Strategy: If not using webhooks, poll status every 30-60 seconds
Text Optimization: Break extremely long texts into smaller chunks for better processing