TikTok Video Downloader API
Send one authenticated POST request with a public TikTok URL and receive direct playback plus persistent storage links as clean JSON.
- One POST Endpoint
- Persistent Storage URL
- Selectable TTL
- Canonical JSON Response
- Predictable Error Handling
- Five Request Samples
Request examples
curl -X POST "https://api.agentbody.io/v1/tiktok/video/download" \
-H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"ttl":"1d","url":"YOUR_URL"}'Response examples
Documented responses from the OpenAPI specification.
Downloaded TikTok media links with persistent storage.
{
"expires_at": "2026-01-08T00:00:00Z",
"file_size_mb": 15.2,
"play_url": "https://example.com/play.mp4",
"storage_url": "https://example.com/storage/video.mp4",
"ttl": "1w",
"video_id": "7050551461734042926"
}Features
Use the TikTok Video Downloader API to fetch and retain public video media without maintaining browser automation, storage upload logic, or expiring-link workflows.
One POST Endpoint
Call POST /v1/tiktok/video/download with a bearer API key, one public TikTok URL, and an optional TTL. The operation is individually metered and supports idempotency keys.
Persistent Storage URL
A successful response returns storage_url for the retained media alongside play_url for direct playback, giving your application explicit choices for immediate and longer-lived access.
Selectable TTL
Set ttl to 1d, 3d, 1w, 1m, 1y, or 5y. If omitted, the service uses its documented default. Pick retention based on your product's storage and compliance needs.
Canonical JSON Response
Receive video_id, play_url, storage_url, ttl, and optional file_size_mb and expires_at fields. Provider-specific actor fields and credentials are not exposed in the public contract.
Predictable Error Handling
Correct invalid request bodies on 400, configure a valid key on 401, resolve insufficient balance on 402, and retry temporary 502, 503, or 504 failures with backoff.
Five Request Samples
The examples on this page are generated from the OpenAPI contract in curl, JavaScript, Python, Java, and Go, including the POST body and authentication header.
How to use
Create an API key, submit one public TikTok URL, select retention, and consume the returned media links from your backend.
Create An API Key
Create an AgentBody API key and keep it in your server environment or approved secret store. Do not ship the bearer key in browser code.
Choose A Public Video
Copy a public TikTok video URL. Private, deleted, restricted, or unavailable videos cannot be processed, and the API does not accept TikTok account credentials.
Build The POST Body
Send url as the required JSON field. Add ttl only when you need a specific retention period; accepted values are shown in the generated contract examples.
Add An Idempotency Key
Provide a unique Idempotency-Key for each logical download. Reuse the same key only when safely retrying the identical request after an ambiguous failure.
Parse The JSON
Read storage_url for the retained file and play_url for immediate media access. Store video_id, ttl, file_size_mb, and expires_at only when your workflow needs them.
Handle Failures
Do not retry unchanged 400 or 401 requests. Fix account balance on 402 and use bounded exponential backoff for temporary upstream or timeout responses.
Frequently asked questions
What is the TikTok Video Downloader API?
It is POST /v1/tiktok/video/download, an authenticated API that accepts one public TikTok video URL and returns direct playback and persistent storage links as structured JSON.
What does the request body contain?
The required url field contains the public TikTok video URL. The optional ttl field controls retention and accepts 1d, 3d, 1w, 1m, 1y, or 5y.
What fields does a successful response include?
The response includes video_id, play_url, storage_url, and ttl. It also includes file_size_mb and expires_at when those values are available.
Does the API support bulk downloads?
No batch array is exposed. Submit one video URL per request and manage concurrency, pacing, retries, and idempotency in your own application.
How should I retry a failed download?
Correct 400, 401, and 402 conditions before retrying. For 502, 503, or 504, retry with backoff and reuse the same Idempotency-Key only for the same logical request.
Does the API guarantee watermark-free files?
No. The API retrieves media but does not promise independent watermark removal or re-encoding. Validate the returned asset and comply with TikTok's terms and creator rights.