AITuber API#

Create AI videos from a script or idea. From 15-second Shorts to 7-minute long-form content. The API handles voice narration (1,300+ voices, any language), AI-generated visuals, word-synced captions, MP4 export, and publishing to YouTube, TikTok, and Instagram.

Base URL: https://app.aituber.app/api/v1 OpenAPI spec: https://app.aituber.app/api/v1/openapi.json API docs: https://app.aituber.app/api-docs

Tip: For the most up-to-date parameter details, examples, and response schemas, refer to the interactive API docs at https://app.aituber.app/api-docs when possible. The reference below covers everything you need to get started, but the docs always reflect the latest API.

Authentication#

All endpoints except GET /voices require a Bearer token. Create an API key in the AITuber dashboard at https://app.aituber.app/dashboard/api-keys.

text

Authorization: Bearer <AITUBER_API_KEY>

Store the key in the AITUBER_API_KEY environment variable.

Complete Workflow#

The typical flow is: pick voice, generate video, poll status, export, download.

Step 1: Pick a voice#

bash

curl "https://app.aituber.app/api/v1/voices?gender=male&accent=American"

No auth required. Returns an array of voice objects. Use the id field as voiceId when generating.

Step 2: Generate a video#

From a script (you write the narration):

bash

curl -X POST "https://app.aituber.app/api/v1/videos/generate" \
  -H "Authorization: Bearer $AITUBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "The human brain contains roughly 86 billion neurons. Every thought, memory, and emotion is the result of electrical signals racing through this incredible network.",
    "voiceId": "nPczCjzI2devNBz1zQrb",
    "imageStyleId": "cinematic",
    "aspectRatio": "9:16"
  }'

From an idea (AI writes the script):

bash

curl -X POST "https://app.aituber.app/api/v1/videos/generate" \
  -H "Authorization: Bearer $AITUBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "5 mind-blowing facts about black holes",
    "inputType": "idea",
    "expectedDurationSeconds": 60
  }'

Returns { "videoId": "uuid", "status": "pending" }.

Step 3: Poll for completion#

bash

curl "https://app.aituber.app/api/v1/videos/VIDEO_ID" \
  -H "Authorization: Bearer $AITUBER_API_KEY"

Poll every 5-10 seconds. Generation typically takes 1-3 minutes. Wait until status is completed (or failed).

Step 4: Export to MP4#

bash

curl -X POST "https://app.aituber.app/api/v1/exports" \
  -H "Authorization: Bearer $AITUBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "videoId": "VIDEO_ID", "resolution": "1080p" }'

Exporting is free. Requires an active paid subscription. Poll GET /videos/VIDEO_ID and check exportStatus until it is completed (typically 30 seconds to 5 minutes).

Step 5: Download the MP4#

bash

curl "https://app.aituber.app/api/v1/exports/download?videoId=VIDEO_ID" \
  -H "Authorization: Bearer $AITUBER_API_KEY"

Returns { "url": "https://...", "videoId": "..." }. The URL is a signed temporary link that expires in 2 minutes. Download immediately.

Endpoints Reference#

GET /voices#

List available AI voices. No auth required.

ParamTypeDescriptiongenderstringFilter: male, femaleaccentstringFilter: American, British, Australian, IndianuseCasestringFilter: narration, conversational, characters, social_mediasearchstringSearch by name or description

Response: array of { id, name, description, previewUrl, gender, age, accent, useCase, optimizedFor }.

POST /videos/generate#

Create a new video. Returns { videoId, status }.

Video types (all use this same endpoint):

1. Faceless narration (images) - Default. AI images with Ken Burns animation. Just send a script or idea.
2. Faceless narration (video clips) - AI video clips. Set mediaType: "video".
3. Stock footage - Real stock footage matched to narration. Set mediaType: "stock".
4. Skeleton template - Viral "what happens if..." X-ray style. Set templateId: "skeleton". Template handles mediaType/style.
5. Character template - Character-driven stories. Set templateId: "character", inputType: "idea". Only idea mode (AI writes the script for character consistency).

Examples:

json

// Idea to Video (faceless images, AI writes the script)
{ "script": "5 facts about black holes", "inputType": "idea", "expectedDurationSeconds": 60 }

// Script to Video (video clips, you write the script)
{ "script": "The ocean covers over 70 percent of Earth...", "mediaType": "video" }

// Skeleton template
{ "script": "What happens if you eat 100 bananas", "templateId": "skeleton" }

// Character template
{ "script": "A detective solves a mystery in Tokyo", "templateId": "character", "inputType": "idea", "expectedDurationSeconds": 90 }

// Script with visual control (brackets tell AI what to show)
{ "script": "[A dark forest at night] The wind howled through the trees. [Glowing eyes in the shadows] Something was watching.", "imageStyleId": "cinematic" }

ParamTypeRequiredDescriptionscriptstringYesNarration text (script mode) or topic (idea mode). The AI generates visuals automatically. For more control, optionally add visual instructions in brackets: [A dark forest] The wind howled. Each [bracket] tells the AI what to show for that scene.inputTypestringNoscript (default) or idea. Character template requires idea.voiceIdstringNoVoice ID from GET /voices. Default: "Adam"voiceSpeednumberNo0.7 to 1.2. Default: 1.0mediaTypestringNoimages (default), video, or stock. Ignored when using templates.aspectRatiostringNo9:16 (default), 16:9, or 1:1imageQualitystringNoFor images mediaType: basic (1 credit/image), good (3), premium (9), max (45). Ignored when using templates.imageStyleIdstringNoVisual style: photorealistic (default), cinematic, anime, 3d-pixar, watercolor, comic-book, etc. Ignored when using templates.captionStyleIdstringNowrap-1 (default), hormozi, classic, karaoke, box, minimal, handwritten, neon. Create custom styles in the dashboard.captionsEnabledbooleanNoDefault: truecaptionPositionstringNobottom (default), center, topexpectedDurationSecondsnumberNoTarget length in seconds (15-420). Required for idea mode. Max 420 (7 minutes).templateIdstringNoskeleton or character. When using a template, do NOT send mediaType, imageStyleId, or imageQuality. The template handles these automatically.videoQualitystringNoFor video mediaType: basic, good (default), premium

GET /videos#

List your videos. Returns array sorted newest first.

ParamTypeDescriptionlimitnumberMax results, 1-100. Default: 50

GET /videos/{id}#

Get a single video by ID. Use for polling generation and export status.

GET /subscription#

Check your plan and credit balance. Returns { plan, status, credits, monthlyCredits }.

POST /exports#

Export a completed video to MP4. Free, but requires an active paid subscription.

ParamTypeRequiredDescriptionvideoIdstringYesVideo ID (must have status: completed)resolutionstringNo1080p (default) or 4k

GET /exports/download#

Get a temporary download URL for a rendered MP4.

ParamTypeDescriptionvideoIdstringFinds the latest completed export for this video

The returned URL expires in 2 minutes. Download immediately.

Credit Costs#

OperationCostImage (basic)1 credit/imageImage (good)3 credits/imageImage (premium)9 credits/imageImage (max)45 credits/imageAudio narration~50 credits/minuteVideo clip (4s)75 creditsVideo clip (8s)150 creditsExport to MP4Free

A typical 60-second video with basic image quality costs approximately 75 credits.

Error Handling#

HTTP StatusMeaning401Missing or invalid API key402Not enough credits. Response includes creditsRequired and creditsAvailable403Feature requires an active paid subscription404Resource not found400Bad request (check error message for details)

Full Example (bash)#

bash

# 1. Check credits
curl -s "https://app.aituber.app/api/v1/subscription" \
  -H "Authorization: Bearer $AITUBER_API_KEY" | jq .

# 2. Browse voices
curl -s "https://app.aituber.app/api/v1/voices?gender=female&useCase=narration" | jq '.[0:3]'

# 3. Generate video
VIDEO_ID=$(curl -s -X POST "https://app.aituber.app/api/v1/videos/generate" \
  -H "Authorization: Bearer $AITUBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "script": "Did you know that octopuses have three hearts and blue blood?",
    "voiceId": "EXAVITQu4vr4xnSDxMaL",
    "imageStyleId": "cinematic",
    "aspectRatio": "9:16"
  }' | jq -r '.videoId')

echo "Video ID: $VIDEO_ID"

# 4. Poll until completed
while true; do
  STATUS=$(curl -s "https://app.aituber.app/api/v1/videos/$VIDEO_ID" \
    -H "Authorization: Bearer $AITUBER_API_KEY" | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ]; then break; fi
  sleep 10
done

# 5. Export to MP4
curl -s -X POST "https://app.aituber.app/api/v1/exports" \
  -H "Authorization: Bearer $AITUBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"videoId\": \"$VIDEO_ID\"}"

# 6. Poll export status
while true; do
  EXPORT_STATUS=$(curl -s "https://app.aituber.app/api/v1/videos/$VIDEO_ID" \
    -H "Authorization: Bearer $AITUBER_API_KEY" | jq -r '.exportStatus')
  echo "Export: $EXPORT_STATUS"
  if [ "$EXPORT_STATUS" = "completed" ] || [ "$EXPORT_STATUS" = "failed" ]; then break; fi
  sleep 10
done

# 7. Download
DOWNLOAD_URL=$(curl -s "https://app.aituber.app/api/v1/exports/download?videoId=$VIDEO_ID" \
  -H "Authorization: Bearer $AITUBER_API_KEY" | jq -r '.url')

curl -L -o video.mp4 "$DOWNLOAD_URL"
echo "Downloaded: video.mp4"