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 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.

Authorization: Bearer <AITUBER_API_KEY>

Store the key in the AITUBER_API_KEY environment variable.

Complete Workflow

AITuber supports two common flows after generation:

• Export flow: pick voice, generate video, poll status, export, download
• Publish flow: pick voice, generate video, poll status, list channels, publish, poll publication status

Step 1: Pick a voice

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):

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):

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

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

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

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.

Step 6: Publish to connected channels

Publishing requires channels to already be connected in the AITuber dashboard and an active paid subscription with the Publish feature. If the video is not exported yet, the API starts the export automatically.

List channels:

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

Publish:

curl -X POST "https://app.aituber.app/api/v1/publications" \
  -H "Authorization: Bearer $AITUBER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "videoId": "VIDEO_ID",
    "caption": "New short is live",
    "publishNow": true,
    "channels": [
      {
        "channelId": "YOUTUBE_CHANNEL_ID",
        "title": "5 Mind-Blowing Facts",
        "tags": ["facts", "science"],
        "categoryId": "27"
      },
    ]
  }'

Poll publication status:

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

Poll every 10-15 seconds until the upload reaches a stable state such as published, scheduled, or failed.

Endpoints Reference

GET /voices

List available AI voices. No auth required.

Param	Type	Description
gender	string	Filter: male, female
accent	string	Filter: American, British, Australian, Indian
useCase	string	Filter: narration, conversational, characters, social_media
search	string	Search 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:

// 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" }

Param	Type	Required	Description
script	string	Yes	Narration 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.
inputType	string	No	script (default) or idea. Character template requires idea.
voiceId	string	No	Voice ID from GET /voices. Default: "Adam"
voiceSpeed	number	No	0.7 to 1.2. Default: 1.0
mediaType	string	No	images (default), video, or stock. Ignored when using templates.
aspectRatio	string	No	9:16 (default), 16:9, or 1:1
imageQuality	string	No	For images mediaType: basic (1 credit/image), good (3), premium (9), max (45). Ignored when using templates.
imageStyleId	string	No	Visual style: photorealistic (default), cinematic, anime, 3d-pixar, watercolor, comic-book, etc. Ignored when using templates.
captionStyleId	string	No	wrap-1 (default), hormozi, classic, karaoke, box, minimal, handwritten, neon. Create custom styles in the dashboard.
captionsEnabled	boolean	No	Default: true
captionPosition	string	No	bottom (default), center, top
expectedDurationSeconds	number	No	Target length in seconds (15-420). Required for idea mode. Max 420 (7 minutes).
templateId	string	No	skeleton or character. When using a template, do NOT send mediaType, imageStyleId, or imageQuality. The template handles these automatically.
videoQuality	string	No	For video mediaType: basic, good (default), premium

GET /videos

List your videos. Returns array sorted newest first.

Param	Type	Description
limit	number	Max 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.

Param	Type	Required	Description
videoId	string	Yes	Video ID (must have status: completed)
resolution	string	No	1080p (default) or 4k

GET /exports/download

Get a temporary download URL for a rendered MP4.

Param	Type	Description
videoId	string	Finds the latest completed export for this video

The returned URL expires in 2 minutes. Download immediately.

GET /channels

List connected channels for publishing.

Param	Type	Description
platform	string	Optional filter: youtube, instagram, or all

Response items include: id, platform, platformChannelId, channelName, channelUsername, channelThumbnailUrl, subscriberCount, status, lastSyncedAt.

POST /publications

Publish a completed video to one or more connected channels. The API auto-exports to MP4 if needed.

Param	Type	Required	Description
videoId	string	Yes	Video ID from POST /videos/generate or GET /videos
sceneExportId	string	No	Optional export ID if you already have a completed export
caption	string	No	Shared description/caption across platforms
publishNow	boolean	No	true (default) to publish immediately
scheduledAt	string	No	Required when publishNow is false; must be a future ISO 8601 datetime
channels	array	Yes	Array of channel objects with channelId plus platform-specific settings

Per-platform channel settings:

• YouTube: title, tags, categoryId, madeForKids
• Instagram: instagramPlacement, shareToFeed

GET /publications/{publicationId}

Get publication status after publishing.

Response fields include: id, videoId, channelId, title, description, status, platformVideoId, platformVideoUrl, errorMessage, scheduledAt, publishedAt, createdAt.

Credit Costs

Operation	Cost
Image (basic)	1 credit/image
Image (good)	3 credits/image
Image (premium)	9 credits/image
Image (max)	45 credits/image
Audio narration	~50 credits/minute
Video clip (4s)	75 credits
Video clip (8s)	150 credits
Export to MP4	Free

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

Error Handling

HTTP Status	Meaning
401	Missing or invalid API key
402	Not enough credits. Response includes creditsRequired and creditsAvailable
403	Feature requires an active paid subscription
404	Resource not found
400	Bad request (check error message for details)

Full Example (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"