API reference · TikTok

tiktok/bulk/video-metadata

Integrate this model through SandBase's unified API, with production-ready schemas and examples.

APIAsyncOpen model

Production endpoint

Send your first request

OpenAI-compatible endpoint with unified authentication and usage tracking.

POSThttps://api.sandbase.ai/v1/run

Model IDtiktok/bulk/video-metadata

Input Schema

8 parameters · 1 required · 7 optional

Parameter	Type	Required	Description
`postURLs`	array	Required	Add the URLs of posted videos you want to scrape. You can enter URLs one by one, or you can upload or link to a text file.
`resultsPerPage`	integer	Optional	Add the number of related videos you want to scrape for each post URL. This field is applicable when the Scrape related videos option is enabled. · Min: 1 · Max: 1000000 · Default: 1
`scrapeRelatedVideos`	boolean	Optional	Tick to scrape related videos for the post URLs you provide. - The maximum number of scraped related videos is set by the `resultsPerPage` count. · Default: false
`shouldDownloadCovers`	boolean	Optional	Tick to download TikTok video cover images (thumbnails). Note that this will increase time and costs needed to extract the data. · Default: false
`shouldDownloadVideos`	boolean	Optional	This is a charged add-on. Tick to download TikTok videos. · Default: false
`videoKvStoreIdOrName`	string	Optional	Name (or ID) of the Key Value Store where the videos and other media like thumbnails will be stored. Omit to store in the default one. Using this option will provide a named Key-Value store can help bypass data retention and store the content forever until the store is manually deleted.The Key-Value store's name can consist of a versatile combination of uppercase letters, lowercase letters, digits, or hyphens, all without any spaces.
`downloadSubtitlesOptions`	string	Optional	Choose how to handle subtitles and audio transcription for input videos. Subtitles are provided by TikTok for some videos, and transcription means that this Actor will use speech-to-text AI to generate video transcript. · Options: NEVER_DOWNLOAD_SUBTITLES, DOWNLOAD_SUBTITLES, DOWNLOAD_AND_TRANSCRIBE_VIDEOS_WITHOUT_SUBTITLES, TRANSCRIBE_ALL_VIDEOS · Default: "NEVER_DOWNLOAD_SUBTITLES" NEVER_DOWNLOAD_SUBTITLESDOWNLOAD_SUBTITLESDOWNLOAD_AND_TRANSCRIBE_VIDEOS_WITHOUT_SUBTITLESTRANSCRIBE_ALL_VIDEOS
`shouldDownloadSlideshowImages`	boolean	Optional	Tick to download TikTok slideshow images. Note that this will increase costs and time required for scraping. · Default: false

Output Schema

Field	Type	Description
`id`	string	Unique identifier for the generation task
`status`	string	Task status: pending, running, completed, failed, timeout
`model`	string	Model used for the generation
`outputs`	array	Array of output items
`outputs[].url`	string	URL of the generated artifact
`outputs[].content_type`	string	MIME type (e.g. image/png, video/mp4)
`error`	object \| null	Error details if failed, null on success
`error.type`	string	Machine-readable error type code
`error.message`	string	Human-readable error description

Async Workflow

This model uses asynchronous execution. Submit a request and poll for the result.

Submit — POST to /v1/run, receive an id
Poll — GET /v1/run/{id} until status is completed, failed, or timeout
Retrieve — Read outputs from the completed response

Code Examples

Ready-to-run snippets

# Step 1: Submit
curl -X POST https://api.sandbase.ai/v1/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "model": "tiktok/bulk/video-metadata",
  "resultsPerPage": 1,
  "scrapeRelatedVideos": false,
  "shouldDownloadCovers": false,
  "shouldDownloadVideos": false,
  "downloadSubtitlesOptions": "NEVER_DOWNLOAD_SUBTITLES",
  "shouldDownloadSlideshowImages": false,
  "prompt": "a beautiful sunset over mountains"
}'

# Step 2: Poll result (replace <id>)
curl https://api.sandbase.ai/v1/run/<id> \
  -H "Authorization: Bearer YOUR_API_KEY"

← Back to TikTok Video Metadata