Quickstart in 60 seconds
- Get a beta API key from /beta or ask an admin to create one.
- Send a public Threads post URL to
POST /v1/threads/video. - Choose
download_mode: direct URL, metadata only, or temporary proxy token.
curl -X POST https://api.clipmagic.ru/v1/threads/video \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"url":"https://www.threads.net/@example/post/example","download_mode":"proxy","include_metadata":true,"include_thumbnail":true}'Authentication
Use the X-API-Key header on resolve requests. Full API keys are shown once at creation and are stored server-side only as HMAC hashes.
Endpoint: Resolve Threads Video
POST /v1/threads/video accepts a Threads post URL and returns post metadata plus video media variants when available.
| Field | Type | Required | Description |
|---|---|---|---|
| url | string | yes | Public Threads post URL. |
| download_mode | url | metadata_only | proxy | no | Controls whether direct URLs, metadata only, or temporary proxy links are returned. |
| include_metadata | boolean | no | Include post metadata fields. |
| include_thumbnail | boolean | no | Include thumbnail URLs when available. |
download_mode comparison
url
Returns validated media URLs when source allows it. Best for server-side workflows that can handle expiring signed URLs.
metadata_only
Returns post and media metadata without download URLs. Best for testing, indexing and previews.
proxy
Returns temporary /v1/download/:token links. The API streams media and does not store videos permanently.
Code examples
JavaScript
const response = await fetch("https://api.clipmagic.ru/v1/threads/video", {
method: "POST",
headers: { "Content-Type": "application/json", "X-API-Key": process.env.THREADS_API_KEY },
body: JSON.stringify({ url: "https://www.threads.net/@example/post/example", download_mode: "metadata_only" })
});
const data = await response.json();Python
import os, requests
response = requests.post(
"https://api.clipmagic.ru/v1/threads/video",
headers={"X-API-Key": os.environ["THREADS_API_KEY"]},
json={"url": "https://www.threads.net/@example/post/example", "download_mode": "proxy"},
timeout=15,
)
print(response.json())Responses
Success response
{
"success": true,
"source": "threads",
"input_url": "https://www.threads.net/@example/post/example",
"normalized_url": "https://www.threads.net/@example/post/example",
"post": { "id": "123", "username": "example", "permalink": "https://www.threads.net/@example/post/example", "text": "Caption" },
"media": [{ "type": "video", "download_url": "https://api.clipmagic.ru/v1/download/dlt_example", "quality": "720p", "duration_seconds": 12.4 }],
"meta": { "request_id": "req_example", "processing_time_ms": 184 }
}Error response
{ "success": false, "error": { "code": "CONTENT_NOT_ACCESSIBLE", "message": "The Threads post is not publicly accessible or cannot be processed without authorization." }, "meta": { "request_id": "req_example", "processing_time_ms": 122 } }Error code table
| INVALID_URL | The URL is malformed. |
| UNSUPPORTED_DOMAIN | The URL is not a supported Threads domain. |
| VIDEO_NOT_FOUND | No public video was found. |
| CONTENT_NOT_ACCESSIBLE | The post requires login, is private, unavailable or blocked by challenge. |
| SOURCE_TIMEOUT | Threads source did not respond in time. |
| RATE_LIMIT_EXCEEDED | The API key exceeded its configured limit. |
| DOWNLOAD_TOKEN_EXPIRED | The proxy download token expired. |
| DOWNLOAD_TOKEN_CONSUMED | A single-use token has already been used. |
Proxy download flow
Use download_mode=proxy, then call the returned download_url. HEAD /v1/download/:token checks headers without consuming single-use tokens. GET /v1/download/:token streams from the upstream source and enforces byte limits during streaming.
Range requests are supported when the upstream source supports them. Videos are not stored permanently.
Rate limits and beta limitations
Default beta limits are 30 requests per minute, 500 requests per day and 1 GB daily proxy bandwidth unless your key record says otherwise. Live Threads extraction reliability depends on public source availability and should be validated with your own public corpus.
FAQ
Does this bypass login or CAPTCHA?
No. It resolves only public or otherwise authorized content and does not use user cookies.
Do proxy links store video files?
No. The proxy streams bytes and enforces limits; it does not permanently store media.
How do I report a bug?
Send the request ID, endpoint, approximate time, error code and URL category to support@clipmagic.ru. Do not send private credentials.
Where is the changelog?
See docs/Status.md in the repository or the deployment changelog maintained by the operator.