curl -X POST "https://backend-ai.truefans.in/api/external/v1/templates/{template_id}/bulk-generate/" \
-H "Authorization: Bearer $TRUEFAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"rows": [
{"customer_name": "Anmol", "score": "95", "external_id": "usr_9182"},
{"customer_name": "Rahul", "score": "88", "external_id": "usr_4471"}
],
"batch_name": "August campaign"
}'
{
"bulk_job_id": "8c1f2e3a-...",
"status": "pending",
"row_count": 2,
"estimated_credits": "1.36"
}
{ "error": "rows is required and must be a non-empty list of objects" }
{ "error": "rows exceeds the maximum of 20000 per batch", "max_rows": 20000 }
{ "error": "API key required" }
{ "error": "insufficient_credits", "required": "1.36", "available": "0.50" }
{ "error": "Template not found" }
{ "error": "This template has no configured cost — contact support" }
{ "error": "Failed to start batch" }
{ "error": "Billing service unavailable" }
Video Generation
Generate videos
Render one video, or many, from a template in a single call
POST
/
api
/
external
/
v1
/
templates
/
{template_id}
/
bulk-generate
/
curl -X POST "https://backend-ai.truefans.in/api/external/v1/templates/{template_id}/bulk-generate/" \
-H "Authorization: Bearer $TRUEFAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"rows": [
{"customer_name": "Anmol", "score": "95", "external_id": "usr_9182"},
{"customer_name": "Rahul", "score": "88", "external_id": "usr_4471"}
],
"batch_name": "August campaign"
}'
{
"bulk_job_id": "8c1f2e3a-...",
"status": "pending",
"row_count": 2,
"estimated_credits": "1.36"
}
{ "error": "rows is required and must be a non-empty list of objects" }
{ "error": "rows exceeds the maximum of 20000 per batch", "max_rows": 20000 }
{ "error": "API key required" }
{ "error": "insufficient_credits", "required": "1.36", "available": "0.50" }
{ "error": "Template not found" }
{ "error": "This template has no configured cost — contact support" }
{ "error": "Failed to start batch" }
{ "error": "Billing service unavailable" }
Starts rendering one video per row in
rows, all from the same template. Returns immediately with a bulk_job_id — track progress via Get bulk job status or a webhook.
This is the only generation endpoint — for a single video, call it with one row in
rows.Body
A non-empty list of
{variable_name: value} objects, one per video, up to 20,000 per request. Keys should match Get template schema’s variable names — a row missing a key just leaves that variable blank in that row’s video.external_id is a reserved key you can include in any row — your own identifier for that row, echoed back unchanged in the CSV export and usable with Get single video status to check a row before the batch finishes. Not treated as a template variable.rows — not a CSV file or URL — is the only way to submit a batch through this API. Serialize your data directly into the request body.curl -X POST "https://backend-ai.truefans.in/api/external/v1/templates/{template_id}/bulk-generate/" \
-H "Authorization: Bearer $TRUEFAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"rows": [
{"customer_name": "Anmol", "score": "95", "external_id": "usr_9182"},
{"customer_name": "Rahul", "score": "88", "external_id": "usr_4471"}
],
"batch_name": "August campaign"
}'
{
"bulk_job_id": "8c1f2e3a-...",
"status": "pending",
"row_count": 2,
"estimated_credits": "1.36"
}
{ "error": "rows is required and must be a non-empty list of objects" }
{ "error": "rows exceeds the maximum of 20000 per batch", "max_rows": 20000 }
{ "error": "API key required" }
{ "error": "insufficient_credits", "required": "1.36", "available": "0.50" }
{ "error": "Template not found" }
{ "error": "This template has no configured cost — contact support" }
{ "error": "Failed to start batch" }
{ "error": "Billing service unavailable" }
Errors
| Status | Meaning | What to do |
|---|---|---|
400 | rows missing, empty, not a list of objects, or over 20,000 rows | Fix the request body, or split into multiple batches |
401 | Missing or invalid API key | Check the Authorization header |
402 | Insufficient credits | Top up the workspace’s account |
404 | Template not found in this workspace | Confirm the template_id and that the key belongs to the right workspace |
422 | Template has no scenes, or no configured cost | Fix the template in the editor |
500 | Failed to prepare or dispatch the batch after credits were reserved | Credits are reversed on a best-effort basis — verify your balance before retrying |
503 | Billing service temporarily unavailable | Safe to retry |
Response fields
Use with Get bulk job status to track the whole batch.