API Reference

TikVod REST API

Generate short-form videos, preview scripts, and automate publishing from your own backend, no-code stack, or batch pipeline.

Overview

The TikVod API is a RESTful JSON interface. All requests use HTTPS. Responses are JSON unless noted otherwise. Each successful video generation consumes 1 credit.

Base URL

https://api.tikvod.com/v1

API version

2026-03-15

Authentication

Authenticate with a secret API key from your TikVod dashboard under Settings → API keys. Pass the key in the Authorization header.

Example request

curl https://api.tikvod.com/v1/account/credits \
  -H "Authorization: Bearer tv_live_7xK9mP2nQ4rS8tU1vW3yZ5" \
  -H "Content-Type: application/json"

Live keys start with tv_live_. Test keys start with tv_test_ and queue jobs without consuming credits or rendering final output.

Errors

Errors return an appropriate HTTP status code and a JSON body with an error code and human-readable message.

{
  "error": {
    "code": "insufficient_credits",
    "message": "You need at least 1 credit to generate a video.",
    "request_id": "req_8f3a2b1c9d0e"
  }
}

HTTP status	Meaning
400	Invalid parameters
401	Missing or invalid API key
402	Insufficient credits
404	Resource not found
409	Conflict (e.g. job already processing)
429	Rate limit exceeded
500	Internal server error

Rate limits

Default limits are 60 requests per minute per API key and 10 concurrent video jobs. Response headers include current usage:

X-RateLimit-Limit — max requests per window
X-RateLimit-Remaining — requests left
X-RateLimit-Reset — Unix timestamp when the window resets

POST/videos

Create video

Queue a new short-form video generation job. One credit is deducted when the job enters the processing queue.

Request body

Parameter	Type	Description
idea*	string	Topic, prompt, or URL describing the video. Max 2,000 characters.
style*	string	Video format. One of: Faceless story, AI b-roll, Talking avatar, Quiz, Listicle.
voice*	string	Narrator voice ID from GET /voices.
language	string	ISO 639-1 code. Defaults to en.
duration	integer	Target length in seconds. 15–90. Defaults to 45.
resolution	string	1080p or 4k. Defaults to 1080p.
caption_style	string	Caption preset ID from GET /captions/styles.
music	string	Background track mood: upbeat, calm, dramatic, none. Defaults to upbeat.
metadata	object	Optional key-value pairs echoed in webhooks (max 20 keys).

Example request

POST /v1/videos
{
  "idea": "5 morning habits that changed my productivity",
  "style": "Listicle",
  "voice": "aria_us",
  "language": "en",
  "duration": 45,
  "resolution": "1080p",
  "caption_style": "bold_pop",
  "music": "upbeat",
  "metadata": {
    "campaign": "q2_faceless",
    "channel": "tiktok_main"
  }
}

Example response

{
  "id": "vid_9k2mN8pQ4rT6",
  "object": "video",
  "status": "queued",
  "idea": "5 morning habits that changed my productivity",
  "style": "Listicle",
  "voice": "aria_us",
  "duration": 45,
  "resolution": "1080p",
  "credits_used": 1,
  "created_at": "2026-06-16T14:22:01Z",
  "estimated_ready_at": "2026-06-16T14:28:30Z"
}

GET/videos

List videos

Return a paginated list of video jobs for the authenticated account, newest first.

Query parameters

Parameter	Type	Description
limit	integer	Number of results. 1–100. Defaults to 20.
starting_after	string	Cursor for pagination (video ID).
status	string	Filter by queued, processing, completed, or failed.

Example response

{
  "object": "list",
  "data": [
    {
      "id": "vid_9k2mN8pQ4rT6",
      "status": "completed",
      "idea": "5 morning habits that changed my productivity",
      "style": "Listicle",
      "thumbnail_url": "https://cdn.tikvod.com/thumbs/vid_9k2mN8pQ4rT6.jpg",
      "duration": 44,
      "created_at": "2026-06-16T14:22:01Z",
      "completed_at": "2026-06-16T14:27:48Z"
    }
  ],
  "has_more": true,
  "next_cursor": "vid_7h1jK3lM5nP8"
}

GET/videos/{id}

Get video

Retrieve full details for a single video job, including script segments and asset URLs when completed.

Example response

{
  "id": "vid_9k2mN8pQ4rT6",
  "object": "video",
  "status": "completed",
  "idea": "5 morning habits that changed my productivity",
  "style": "Listicle",
  "voice": "aria_us",
  "script": {
    "hook": "You're wasting the first hour of your day.",
    "segments": [
      {
        "index": 0,
        "text": "Habit one: no phone for thirty minutes after waking.",
        "visual_prompt": "sunrise bedroom, phone face down on nightstand"
      }
    ]
  },
  "output": {
    "video_url": "https://cdn.tikvod.com/renders/vid_9k2mN8pQ4rT6.mp4",
    "thumbnail_url": "https://cdn.tikvod.com/thumbs/vid_9k2mN8pQ4rT6.jpg",
    "duration": 44,
    "resolution": "1080p",
    "aspect_ratio": "9:16"
  },
  "created_at": "2026-06-16T14:22:01Z",
  "completed_at": "2026-06-16T14:27:48Z"
}

DELETE/videos/{id}

Cancel video

Cancel a job that is still queued. Credits are refunded automatically. Jobs already processing cannot be cancelled.

Example response

{
  "id": "vid_9k2mN8pQ4rT6",
  "object": "video",
  "status": "cancelled",
  "credits_refunded": 1,
  "cancelled_at": "2026-06-16T14:22:45Z"
}

GET/videos/{id}/download

Download video

Return a time-limited signed URL for the rendered MP4. Only available when status is completed.

Example response

{
  "id": "vid_9k2mN8pQ4rT6",
  "download_url": "https://cdn.tikvod.com/renders/vid_9k2mN8pQ4rT6.mp4?sig=...",
  "expires_at": "2026-06-16T15:27:48Z",
  "file_size_bytes": 18429312,
  "content_type": "video/mp4"
}

POST/scripts/preview

Preview script

Generate a hook-first script from an idea without starting a render. Does not consume credits.

Request body

Parameter	Type	Description
idea*	string	Video topic or prompt.
style*	string	Target video format.
duration	integer	Target length in seconds. Defaults to 45.

Example response

{
  "object": "script_preview",
  "hook": "Most people skip the one habit that actually sticks.",
  "segments": [
    { "text": "Start with water before coffee.", "estimated_seconds": 4 },
    { "text": "Write three priorities, not twenty.", "estimated_seconds": 5 }
  ],
  "word_count": 112,
  "estimated_duration": 43
}

GET/voices

List voices

Return all available AI narrator voices with locale, gender, and sample audio URLs.

Example response

{
  "object": "list",
  "data": [
    {
      "id": "aria_us",
      "name": "Aria (US)",
      "locale": "en-US",
      "gender": "female",
      "style": "conversational",
      "preview_url": "https://cdn.tikvod.com/voices/aria_us.mp3"
    },
    {
      "id": "leo_uk",
      "name": "Leo (UK)",
      "locale": "en-GB",
      "gender": "male",
      "style": "authoritative",
      "preview_url": "https://cdn.tikvod.com/voices/leo_uk.mp3"
    },
    {
      "id": "mia_calm",
      "name": "Mia (calm)",
      "locale": "en-US",
      "gender": "female",
      "style": "soft",
      "preview_url": "https://cdn.tikvod.com/voices/mia_calm.mp3"
    },
    {
      "id": "max_energetic",
      "name": "Max (energetic)",
      "locale": "en-US",
      "gender": "male",
      "style": "high_energy",
      "preview_url": "https://cdn.tikvod.com/voices/max_energetic.mp3"
    }
  ]
}

GET/styles

List styles

Return supported video formats with recommended use cases and default visual settings.

Example response

{
  "object": "list",
  "data": [
    {
      "id": "faceless_story",
      "name": "Faceless story",
      "description": "Narrated story with stock and AI b-roll. Best for facts, history, and explainers."
    },
    {
      "id": "ai_broll",
      "name": "AI b-roll",
      "description": "Heavy AI-generated visuals synced to every line."
    },
    {
      "id": "talking_avatar",
      "name": "Talking avatar",
      "description": "On-screen presenter with lip-synced narration."
    },
    {
      "id": "quiz",
      "name": "Quiz",
      "description": "Question-and-answer format with animated choices."
    },
    {
      "id": "listicle",
      "name": "Listicle",
      "description": "Numbered list format optimized for retention hooks."
    }
  ]
}

GET/captions/styles

Caption styles

Return animated subtitle presets available for video generation.

Example response

{
  "object": "list",
  "data": [
    { "id": "bold_pop", "name": "Bold Pop", "words_per_line": 3 },
    { "id": "minimal_white", "name": "Minimal White", "words_per_line": 4 },
    { "id": "karaoke_neon", "name": "Karaoke Neon", "words_per_line": 2 }
  ]
}

GET/account/credits

Credit balance

Return the current credit balance for the authenticated account.

Example response

{
  "object": "credit_balance",
  "credits": 24,
  "currency": "usd",
  "cost_per_video": 1.00,
  "updated_at": "2026-06-16T14:20:00Z"
}

POST/videos/{id}/publish

Publish video

Schedule or immediately publish a completed video to a connected social account.

Request body

Parameter	Type	Description
platform*	string	tiktok, youtube_shorts, instagram_reels, or snapchat.
account_id*	string	Connected account ID from the TikVod dashboard.
caption	string	Post caption including hashtags. Max 2,200 characters.
scheduled_at	string	ISO 8601 timestamp for scheduled publish. Omit for immediate post.

Example response

{
  "id": "pub_3nM7pQ9rS2tU",
  "object": "publish_job",
  "video_id": "vid_9k2mN8pQ4rT6",
  "platform": "tiktok",
  "status": "scheduled",
  "scheduled_at": "2026-06-17T09:00:00Z",
  "created_at": "2026-06-16T14:30:00Z"
}

Webhooks

Register webhook endpoints in your dashboard to receive real-time events when video jobs change state. Payloads are signed with TikVod-Signature using HMAC SHA-256.

Event types

video.queued — job accepted
video.processing — render started
video.completed — render finished
video.failed — job failed; credit refunded
publish.completed — social post live

Example payload

{
  "id": "evt_4pR8sT2vX6yZ",
  "object": "event",
  "type": "video.completed",
  "created_at": "2026-06-16T14:27:48Z",
  "data": {
    "id": "vid_9k2mN8pQ4rT6",
    "status": "completed",
    "output": {
      "video_url": "https://cdn.tikvod.com/renders/vid_9k2mN8pQ4rT6.mp4",
      "thumbnail_url": "https://cdn.tikvod.com/thumbs/vid_9k2mN8pQ4rT6.jpg",
      "duration": 44
    },
    "metadata": {
      "campaign": "q2_faceless",
      "channel": "tiktok_main"
    }
  }
}

Respond with HTTP 2xx within 10 seconds. Non-2xx responses trigger up to five retries with exponential backoff over 24 hours.