Replace Actors
Generate Replace Actor Video
Create a motion-transfer job that applies reference video movement to a supplied character image.
POST
/
v1
/
replace-actors
/
generations
Generate Replace Actor Video
curl --request POST \
--url https://api.turboads.ai/v1/replace-actors/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"project_id": "j97project123abc456def789",
"image_url": "https://example.com/character.png",
"video_url": "https://example.com/reference-video.mp4",
"prompt": "Keep the same movement and product interaction from the reference video",
"duration": 8,
"aspect_ratio": "9:16"
}
'import requests
url = "https://api.turboads.ai/v1/replace-actors/generations"
payload = {
"project_id": "j97project123abc456def789",
"image_url": "https://example.com/character.png",
"video_url": "https://example.com/reference-video.mp4",
"prompt": "Keep the same movement and product interaction from the reference video",
"duration": 8,
"aspect_ratio": "9:16"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
project_id: 'j97project123abc456def789',
image_url: 'https://example.com/character.png',
video_url: 'https://example.com/reference-video.mp4',
prompt: 'Keep the same movement and product interaction from the reference video',
duration: 8,
aspect_ratio: '9:16'
})
};
fetch('https://api.turboads.ai/v1/replace-actors/generations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.turboads.ai/v1/replace-actors/generations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'project_id' => 'j97project123abc456def789',
'image_url' => 'https://example.com/character.png',
'video_url' => 'https://example.com/reference-video.mp4',
'prompt' => 'Keep the same movement and product interaction from the reference video',
'duration' => 8,
'aspect_ratio' => '9:16'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.turboads.ai/v1/replace-actors/generations"
payload := strings.NewReader("{\n \"project_id\": \"j97project123abc456def789\",\n \"image_url\": \"https://example.com/character.png\",\n \"video_url\": \"https://example.com/reference-video.mp4\",\n \"prompt\": \"Keep the same movement and product interaction from the reference video\",\n \"duration\": 8,\n \"aspect_ratio\": \"9:16\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.turboads.ai/v1/replace-actors/generations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"project_id\": \"j97project123abc456def789\",\n \"image_url\": \"https://example.com/character.png\",\n \"video_url\": \"https://example.com/reference-video.mp4\",\n \"prompt\": \"Keep the same movement and product interaction from the reference video\",\n \"duration\": 8,\n \"aspect_ratio\": \"9:16\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.turboads.ai/v1/replace-actors/generations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"project_id\": \"j97project123abc456def789\",\n \"image_url\": \"https://example.com/character.png\",\n \"video_url\": \"https://example.com/reference-video.mp4\",\n \"prompt\": \"Keep the same movement and product interaction from the reference video\",\n \"duration\": 8,\n \"aspect_ratio\": \"9:16\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "j97video123abc456def789",
"status": "pending"
}
}{
"error": {
"code": "invalid_request",
"message": "Required fields are missing or malformed."
}
}{
"error": {
"code": "unauthorized",
"message": "Missing, invalid, or revoked API key."
}
}{
"error": {
"code": "insufficient_credits",
"message": "Insufficient credits. Required: 8, Available: 2"
}
}{
"error": {
"code": "forbidden",
"message": "Project does not belong to this API key workspace."
}
}{
"error": {
"code": "not_found",
"message": "Resource not found."
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded."
},
"retry_after_ms": 1200
}{
"error": {
"code": "internal_error",
"message": "Something went wrong."
}
}Authorizations
Your TurboAds API key
Body
application/json
Provide either image_file_id and video_file_id from file uploads, or image_url and video_url.
Existing project ID in the API key workspace.
Public character image URL. Use image_file_id instead when uploading through the API.
Public motion reference video URL. Use video_file_id instead when uploading through the API.
Optional context for the replacement job.
Reference video duration in seconds.
Required range:
3 <= x <= 30Available options:
1:1, 9:16, 16:9 Completed image file upload ID for the replacement character image.
Completed video file upload ID for the motion reference video.
Response
Replace Actor generation job created
Show child attributes
Show child attributes
Previous
Get Replace Actor StatusGet the current status and metadata for a Replace Actor generation job.
Next
⌘I
Generate Replace Actor Video
curl --request POST \
--url https://api.turboads.ai/v1/replace-actors/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"project_id": "j97project123abc456def789",
"image_url": "https://example.com/character.png",
"video_url": "https://example.com/reference-video.mp4",
"prompt": "Keep the same movement and product interaction from the reference video",
"duration": 8,
"aspect_ratio": "9:16"
}
'import requests
url = "https://api.turboads.ai/v1/replace-actors/generations"
payload = {
"project_id": "j97project123abc456def789",
"image_url": "https://example.com/character.png",
"video_url": "https://example.com/reference-video.mp4",
"prompt": "Keep the same movement and product interaction from the reference video",
"duration": 8,
"aspect_ratio": "9:16"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
project_id: 'j97project123abc456def789',
image_url: 'https://example.com/character.png',
video_url: 'https://example.com/reference-video.mp4',
prompt: 'Keep the same movement and product interaction from the reference video',
duration: 8,
aspect_ratio: '9:16'
})
};
fetch('https://api.turboads.ai/v1/replace-actors/generations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.turboads.ai/v1/replace-actors/generations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'project_id' => 'j97project123abc456def789',
'image_url' => 'https://example.com/character.png',
'video_url' => 'https://example.com/reference-video.mp4',
'prompt' => 'Keep the same movement and product interaction from the reference video',
'duration' => 8,
'aspect_ratio' => '9:16'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.turboads.ai/v1/replace-actors/generations"
payload := strings.NewReader("{\n \"project_id\": \"j97project123abc456def789\",\n \"image_url\": \"https://example.com/character.png\",\n \"video_url\": \"https://example.com/reference-video.mp4\",\n \"prompt\": \"Keep the same movement and product interaction from the reference video\",\n \"duration\": 8,\n \"aspect_ratio\": \"9:16\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.turboads.ai/v1/replace-actors/generations")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"project_id\": \"j97project123abc456def789\",\n \"image_url\": \"https://example.com/character.png\",\n \"video_url\": \"https://example.com/reference-video.mp4\",\n \"prompt\": \"Keep the same movement and product interaction from the reference video\",\n \"duration\": 8,\n \"aspect_ratio\": \"9:16\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.turboads.ai/v1/replace-actors/generations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"project_id\": \"j97project123abc456def789\",\n \"image_url\": \"https://example.com/character.png\",\n \"video_url\": \"https://example.com/reference-video.mp4\",\n \"prompt\": \"Keep the same movement and product interaction from the reference video\",\n \"duration\": 8,\n \"aspect_ratio\": \"9:16\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "j97video123abc456def789",
"status": "pending"
}
}{
"error": {
"code": "invalid_request",
"message": "Required fields are missing or malformed."
}
}{
"error": {
"code": "unauthorized",
"message": "Missing, invalid, or revoked API key."
}
}{
"error": {
"code": "insufficient_credits",
"message": "Insufficient credits. Required: 8, Available: 2"
}
}{
"error": {
"code": "forbidden",
"message": "Project does not belong to this API key workspace."
}
}{
"error": {
"code": "not_found",
"message": "Resource not found."
}
}{
"error": {
"code": "rate_limited",
"message": "Rate limit exceeded."
},
"retry_after_ms": 1200
}{
"error": {
"code": "internal_error",
"message": "Something went wrong."
}
}
