Name: TikTok Video API: Get Video URL, Caption, Thumbnail
Brand: cqqrory
SKU: api-cqqrory-tiktok-video-metadata-api
Availability: InStock
Author: API Market

rory chen

# TikTok Video & Metadata API

## Overview

The TikTok Video & Metadata API turns the URL of a public TikTok video into a temporary video URL and the public metadata available for that video. There is one endpoint: you POST a TikTok video link (a full `tiktok.com/@user/video/...` URL or a `vm.tiktok.com`, `vt.tiktok.com` or `/t/` short link) and get back the video ID, media type, a temporary MP4 URL, a temporary thumbnail URL when one is available, the public caption and the duration in seconds. When a video cannot be resolved, the same endpoint returns a consistent JSON error with a code, a message and a `request_id`.

It is built for developers who need a server-side resolution step inside their own workflow, such as a creator media library importer, a content review or moderation tool, metadata enrichment, or backend automation that turns a video link into structured JSON. It works with public videos only, needs no TikTok login, cookies or session tokens, and should only be used with content you own or are authorized to process. The `video_url` and `thumbnail_url` values are signed TikTok CDN links that expire, so download the media promptly and store the original video URL and `video_id` if you need a lasting reference.

## Features

*   **1 endpoint**: `POST /v1/media/resolve` takes one TikTok video URL and returns the resolved media and metadata in a single JSON response.
*   **Full and short links**: Accepts full TikTok video URLs and `vm.tiktok.com`, `vt.tiktok.com` and `/t/` short links.
*   **Video and metadata in one call**: Returns `video_id`, `media_type`, a temporary `video_url`, a temporary `thumbnail_url` when available, the public `caption` and `duration_seconds`.
*   **Public videos only, no login**: Resolves publicly accessible videos without a TikTok account, password, cookie or session token.
*   **Temporary signed media links**: `video_url` and `thumbnail_url` point to TikTok's CDN and carry time-limited signatures, so they are meant to be used right away.
*   **Optional fetch headers**: When the media URL needs them, the response can include a `request_headers` object with safe `User-Agent`, `Referer` or `Origin` values to send when downloading. It never contains cookies or credentials.
*   **Consistent errors**: Failures return `success: false` with an `error.code`, an `error.message` and a `request_id` for support.
*   **Rate limit**: 1 request per second on every plan (BASIC, PRO and ULTRA).

## Use Cases

*   **Creator media library**: Import your own or creator-authorized TikTok videos into a media library by pasting the link.
*   **Content review and moderation**: Pull the video file, thumbnail and caption into an internal review tool for content you are permitted to process.
*   **Metadata enrichment**: Add caption, duration and video ID to records that only hold a TikTok link.
*   **Authorized archiving**: Save a copy of creator-authorized public videos while the signed media link is still valid.
*   **Backend automation**: Turn a public TikTok video link into structured JSON as one step in a larger pipeline.
*   **Prototyping**: Test and prototype applications that work with authorized public TikTok video URLs on the free BASIC plan.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/cqqrory/tiktok-video-metadata-api
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Resolve a public TikTok video

Resolves one public TikTok video URL into a temporary video URL and its public metadata: source URL, video ID, media type, thumbnail URL, caption and duration. Send the body as JSON with `Content-Type: application/json`. The body accepts only the `url` field; any other property is rejected with `400`. Photo posts, live streams, private, login-only and follower-only content are not supported.

**Method:** `POST`

**Endpoint:** `/v1/media/resolve`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `url` | body | HTTPS URL of a public TikTok video, such as `https://www.tiktok.com/@user/video/<id>`, or a `vm.tiktok.com`, `vt.tiktok.com` or `/t/` short link. Photo post URLs are rejected. | string (URI) | Yes | - | - |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/cqqrory/tiktok-video-metadata-api/v1/media/resolve" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@tiktok/video/7106594312292453675"}'
```

**Example Response (200 OK, abridged):**

The signed query strings on `video_url` and `thumbnail_url` are shortened with `...`. Every other value is as returned.

```json
{
  "success": true,
  "source_url": "https://www.tiktok.com/@tiktok/video/7106594312292453675",
  "video_id": "7106594312292453675",
  "media_type": "video",
  "video_url": "https://v19.tiktokcdn-us.com/11125f898c3bbe9b055814a7232f80c7/6acfde42/video/tos/useast5/tos-useast5-v-27dcd7-tx/3b1e3e03a4fe4d4f825b981b86870986/?...",
  "thumbnail_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-p-0068-tx/beee36ba02ef449397b2d128bc32dd9d_1654632931~tplv-tiktokx-origin.image?...",
  "caption": "Whether you are playing to create or playing to survive, you can celebrate all things #Minecraft on TikTok",
  "duration_seconds": 24
}
```

**Response fields:**

| Field | Type | Description |
|---|---|---|
| `success` | boolean | `true` when the video was resolved. |
| `source_url` | string | The TikTok URL you sent. |
| `video_id` | string | The TikTok video ID. Store this with `source_url` as the lasting reference. |
| `media_type` | string | Always `video` in the current version. |
| `video_url` | string | Signed TikTok CDN link to the MP4. It expires, so download it promptly. |
| `thumbnail_url` | string | Signed TikTok CDN link to the thumbnail. It expires too. Omitted when no thumbnail is available. |
| `caption` | string | The public caption of the video. |
| `duration_seconds` | number or null | Video length in seconds, or `null` when not available. |
| `request_headers` | object | Optional. Safe `User-Agent`, `Referer` or `Origin` headers to send when fetching `video_url`. Only present when needed. |

**Example Error Response (404 Not Found):**

Returned for a video that does not exist, or is private or otherwise unavailable.

```json
{
  "success": false,
  "error": {
    "code": "media_not_public",
    "message": "media is private, unavailable, or has no public video"
  },
  "request_id": "bb5f09d5-6769-4d4a-9b60-9930ee16bcb3"
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The public video was resolved and the media URLs and metadata are in the response body. |
| 400 | Bad Request | The body is not valid JSON, `url` is missing or not a supported TikTok video URL, the link is a photo post, the body has extra properties, or the `x-api-market-key` header is missing. Fix the input before retrying. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The video is private, deleted, restricted, login-only or follower-only, or has no public video (`media_not_public`). Do not retry it as a temporary failure. |
| 429 | Too Many Requests | You went over 1 request per second, used up your plan's call quota, or the service's own request limit was reached. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |
| 502 | Bad Gateway | The upstream platform or proxy request failed. Retry later with backoff. |
| 503 | Service Unavailable | The resolver is temporarily unavailable or busy. Retry later with backoff. |
| 504 | Gateway Timeout | Resolving the video took longer than the allowed processing time. Retry later with backoff. |

## Rate Limits

Every plan allows 1 request per second: BASIC (free, 20 calls), PRO (US$9.99 per month, 250 calls) and ULTRA (US$24.99 per month, 1,000 calls). All three plans use hard limits, so calls stop when the plan's quota is used up. The free BASIC plan is a 7-day trial on API.market. Requests above 1 per second, or past your quota, return `429 Too Many Requests`. Space out batch jobs to at most one call per second, back off before retrying, and honour any `Retry-After` header. Use bounded retries for `429`, `502`, `503` and `504`, and do not retry `400` or `404` responses without changing the input.

## FAQ

**How long do the returned video and thumbnail URLs work?**

They are signed TikTok CDN links with time-limited parameters, and they can expire without notice. Download the video and thumbnail as soon as you get the response. Do not store `video_url` or `thumbnail_url` as permanent links; keep the original `source_url` and `video_id` instead and call the endpoint again when you need a fresh link.

**Does the API work with private TikTok videos?**

No. It supports public videos only. Private, deleted, restricted, login-only and follower-only content returns `404` with the code `media_not_public`. The API does not bypass privacy settings.

**Do I need to send a TikTok account, cookie or token?**

No. The API needs no TikTok login, password, cookie, session identifier or access token, and you should never send any of them. Your API.market key in the `x-api-market-key` header is the only key you need.

**Which URL formats are accepted?**

Full HTTPS video URLs like `https://www.tiktok.com/@user/video/<id>` and short links from `vm.tiktok.com`, `vt.tiktok.com` and `tiktok.com/t/`. Photo posts, image-only posts, live streams and separate audio extraction are not supported.

**Why did a URL that worked before stop resolving?**

The owner may have deleted the video or changed its visibility, access may have been restricted, or TikTok may have changed how the public video is delivered. A video that resolves today is not guaranteed to resolve later.

**How fast is a call?**

In our tests through the API.market gateway, a successful resolve took about 3.1 seconds and a not-found response about 2.4 seconds. Set a client timeout well above that, since time depends on the upstream service.

**Can I use any public video?**

Use the API only with content you own or are authorized to access and process. A successful response only gives you technical resolution data; it does not grant rights to copy, publish or redistribute the video.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


TikTok video API: resolve a public TikTok link into a temporary MP4 URL, thumbnail, caption, video ID and duration as JSON. No login or cookies needed.

TikTok Video API: Get Video URL, Caption, Thumbnail