curl --request POST \
--url https://api.tella.com/v1/library/imports \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://tella.com",
"scroll": true,
"video": true,
"videoId": "vid_abc123def456"
}
'import requests
url = "https://api.tella.com/v1/library/imports"
payload = {
"url": "https://tella.com",
"scroll": True,
"video": True,
"videoId": "vid_abc123def456"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://tella.com',
scroll: true,
video: true,
videoId: 'vid_abc123def456'
})
};
fetch('https://api.tella.com/v1/library/imports', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tella.com/v1/library/imports",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://tella.com',
'scroll' => true,
'video' => true,
'videoId' => 'vid_abc123def456'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tella.com/v1/library/imports"
payload := strings.NewReader("{\n \"url\": \"https://tella.com\",\n \"scroll\": true,\n \"video\": true,\n \"videoId\": \"vid_abc123def456\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tella.com/v1/library/imports")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://tella.com\",\n \"scroll\": true,\n \"video\": true,\n \"videoId\": \"vid_abc123def456\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/library/imports")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://tella.com\",\n \"scroll\": true,\n \"video\": true,\n \"videoId\": \"vid_abc123def456\"\n}"
response = http.request(request)
puts response.read_body{
"import": {
"id": "mi_abc123def456",
"status": "running",
"error": "<string>",
"item": {
"id": "media_abc123def456",
"name": "Intro camera take",
"scope": "private",
"type": "video",
"category": "Everyday",
"createdAt": "<string>",
"dimensions": {
"height": 0,
"width": 0
},
"durationMs": 4200,
"link": "<string>",
"presetId": "cha-ching",
"sourceId": "su_abc123def456",
"summary": "<string>",
"tags": [
"<string>"
],
"updatedAt": "<string>",
"url": "<string>"
}
}
}{
"import": {
"id": "mi_abc123def456",
"status": "running",
"error": "<string>",
"item": {
"id": "media_abc123def456",
"name": "Intro camera take",
"scope": "private",
"type": "video",
"category": "Everyday",
"createdAt": "<string>",
"dimensions": {
"height": 0,
"width": 0
},
"durationMs": 4200,
"link": "<string>",
"presetId": "cha-ching",
"sourceId": "su_abc123def456",
"summary": "<string>",
"tags": [
"<string>"
],
"updatedAt": "<string>",
"url": "<string>"
}
}
}{
"docsUrl": "https://docs.tella.com/",
"error": "bad_request",
"message": "The request was malformed or contained invalid parameters."
}{
"docsUrl": "https://docs.tella.com/",
"error": "unauthorized",
"message": "Authentication is required. Provide a valid API key."
}{
"docsUrl": "https://docs.tella.com/",
"error": "forbidden",
"message": "You don't have permission to access this resource."
}{
"docsUrl": "https://docs.tella.com/",
"error": "not_found",
"message": "The requested resource was not found."
}{
"docsUrl": "https://docs.tella.com/",
"error": "conflict",
"message": "The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles."
}{
"docsUrl": "https://docs.tella.com/",
"error": "rate_limited",
"message": "You have exceeded the rate limit. Please slow down."
}{
"docsUrl": "https://docs.tella.com/",
"error": "server_error",
"message": "An unexpected error occurred"
}{
"docsUrl": "https://docs.tella.com/",
"error": "not_implemented",
"message": "The requested operation is not implemented."
}{
"docsUrl": "https://docs.tella.com/",
"error": "unavailable",
"message": "A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay."
}Import media from a URL
Brings media into Tella from a link. A public web page is captured above the fold at 1920×1080 (or, with scroll=true, recorded scrolling as video); a single post on X, Instagram, LinkedIn or TikTok is cropped to its embed card. These finish in this request (allow up to two minutes) and answer 201 with status: completed. A link to a single video is downloaded in the background and answers 202 with status: running: poll GET /v1/library/imports/{id}?videoId=… every 5-10 seconds until it is completed or failed. Video links need videoId and land in that video’s library; everything else lands in your private library unless you pass videoId. Place item.sourceId as an overlay or layout media. Only import media you own or have the rights to use. Private pages, social profiles and feeds, and private, members-only or age-restricted videos are not supported. Use an Idempotency-Key when retrying to avoid duplicate imports.
curl --request POST \
--url https://api.tella.com/v1/library/imports \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://tella.com",
"scroll": true,
"video": true,
"videoId": "vid_abc123def456"
}
'import requests
url = "https://api.tella.com/v1/library/imports"
payload = {
"url": "https://tella.com",
"scroll": True,
"video": True,
"videoId": "vid_abc123def456"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://tella.com',
scroll: true,
video: true,
videoId: 'vid_abc123def456'
})
};
fetch('https://api.tella.com/v1/library/imports', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tella.com/v1/library/imports",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://tella.com',
'scroll' => true,
'video' => true,
'videoId' => 'vid_abc123def456'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tella.com/v1/library/imports"
payload := strings.NewReader("{\n \"url\": \"https://tella.com\",\n \"scroll\": true,\n \"video\": true,\n \"videoId\": \"vid_abc123def456\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tella.com/v1/library/imports")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://tella.com\",\n \"scroll\": true,\n \"video\": true,\n \"videoId\": \"vid_abc123def456\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/library/imports")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://tella.com\",\n \"scroll\": true,\n \"video\": true,\n \"videoId\": \"vid_abc123def456\"\n}"
response = http.request(request)
puts response.read_body{
"import": {
"id": "mi_abc123def456",
"status": "running",
"error": "<string>",
"item": {
"id": "media_abc123def456",
"name": "Intro camera take",
"scope": "private",
"type": "video",
"category": "Everyday",
"createdAt": "<string>",
"dimensions": {
"height": 0,
"width": 0
},
"durationMs": 4200,
"link": "<string>",
"presetId": "cha-ching",
"sourceId": "su_abc123def456",
"summary": "<string>",
"tags": [
"<string>"
],
"updatedAt": "<string>",
"url": "<string>"
}
}
}{
"import": {
"id": "mi_abc123def456",
"status": "running",
"error": "<string>",
"item": {
"id": "media_abc123def456",
"name": "Intro camera take",
"scope": "private",
"type": "video",
"category": "Everyday",
"createdAt": "<string>",
"dimensions": {
"height": 0,
"width": 0
},
"durationMs": 4200,
"link": "<string>",
"presetId": "cha-ching",
"sourceId": "su_abc123def456",
"summary": "<string>",
"tags": [
"<string>"
],
"updatedAt": "<string>",
"url": "<string>"
}
}
}{
"docsUrl": "https://docs.tella.com/",
"error": "bad_request",
"message": "The request was malformed or contained invalid parameters."
}{
"docsUrl": "https://docs.tella.com/",
"error": "unauthorized",
"message": "Authentication is required. Provide a valid API key."
}{
"docsUrl": "https://docs.tella.com/",
"error": "forbidden",
"message": "You don't have permission to access this resource."
}{
"docsUrl": "https://docs.tella.com/",
"error": "not_found",
"message": "The requested resource was not found."
}{
"docsUrl": "https://docs.tella.com/",
"error": "conflict",
"message": "The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles."
}{
"docsUrl": "https://docs.tella.com/",
"error": "rate_limited",
"message": "You have exceeded the rate limit. Please slow down."
}{
"docsUrl": "https://docs.tella.com/",
"error": "server_error",
"message": "An unexpected error occurred"
}{
"docsUrl": "https://docs.tella.com/",
"error": "not_implemented",
"message": "The requested operation is not implemented."
}{
"docsUrl": "https://docs.tella.com/",
"error": "unavailable",
"message": "A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay."
}Authorizations
API key obtained from your Tella account settings
Body
A public web page, a single post on X, Instagram, LinkedIn or TikTok, or a link to a single video on YouTube, X, Instagram or TikTok. A missing scheme defaults to HTTPS.
1"https://tella.com"
Record a scrolling web page as video instead of a still (default false). Ignored for social posts and video links.
Omit to download every video link, and X and Instagram /p/ posts that hold a video. false captures the link's page or card instead; true downloads a post without checking first that it holds one.
Save into this video's own library instead of your private library. You must be able to edit it. Required for video downloads.
"vid_abc123def456"
Response
Captured and saved to the library
Hide child attributes
Hide child attributes
The library item the import is saved as; poll with it
"mi_abc123def456"
Page and post captures are completed at once; video links are running until downloaded
running, completed, failed Why the import failed, set when status is failed
The finished library item, set when status is completed: an image for a still, a video for a scrolling page or video link. Place item.sourceId with overlays or layout media.
Hide child attributes
Hide child attributes
Unique library item identifier
"media_abc123def456"
Display name shown in the library
"Intro camera take"
Where the item lives: a library scope, video for an image brought into one video's library, pinterest, arena or mymind for an image still in the connected service, or vintage for a shot in Tella's vintage film catalog
private, workspace, default, video, pinterest, arena, mymind, vintage "private"
The kind of media the item holds
image, video, sound-effect, music, lut, screenshot, font "video"
Catalog grouping, for default items only — the same grouping the editor's sound effects and background music panels show
"Everyday"
ISO-8601 creation timestamp. Absent for default catalog items, which are served from Tella's catalog rather than stored as rows.
Duration in milliseconds, for time-based media
4200
For pinterest, arena and mymind items: the page the pin or save links to. For vintage items: the film's archive page
Preset ID, for default catalog items only. A preset has no source, so pass this instead of sourceId: a sound-effect preset goes to POST /v1/videos/{id}/clips/{clipId}/sound-effects (placing it copies the effect into a source owned by your workspace), a music preset to PUT /v1/videos/{id}/background-music.
"cha-ching"
Source ID. Pass it anywhere a sourceId is accepted — clips, layouts, overlays, sound effects. Present for every item added through this API, including images. Absent for items added in the editor, which have no source, for music, LUT and font items, and for default catalog items, which use presetId instead.
"su_abc123def456"
For mymind items: mymind's AI summary of the save
For mymind items: the save's tags
ISO-8601 update timestamp. Absent for default catalog items.
Hosted media URL, for image, screenshot, music, lut and font items, for vintage shots (a preview of the shot), and for default catalog items, where it is a publicly fetchable preview of the audio (for music presets it is also the track the video will play). API-created images expose this alongside sourceId; use sourceId to place the image on a clip, since overlays and layout media do not accept URLs. Editor-created screenshot items have a URL but no sourceId; use POST /v1/library/screenshots to capture a new placeable image or video.
Was this page helpful?