---
title: "Import media from a URL"
method: POST
path: "/v1/library/imports"
tags: ["Library"]
---

# Import media from a URL

`POST /v1/library/imports`

## Request

- Base URL: `https://api.tella.com`
- URL: `https://api.tella.com/v1/library/imports`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/withchima/apis/tella-public-api/docs/v1/library/imports/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Request body

- StartImportRequest
  - `scroll` boolean: Record a scrolling web page as video instead of a still (default false). Ignored for social posts and video links.
  - `url` string, required: 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.
  - `video` boolean: 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.
  - `videoId` string: Save into this video's own library instead of your private library. You must be able to edit it. Required for video downloads.

## Response `201`

Captured and saved to the library

- ImportResponse
  - `import` Import, required
    - `error` string: Why the import failed, set when `status` is `failed`
    - `id` string, required: The library item the import is saved as; poll with it
    - `item` LibraryItem: A placeable piece of media — either saved to a workspace's library, or an entry in Tella's curated catalog
      - `category` string: Catalog grouping, for `default` items only — the same grouping the editor's sound effects and background music panels show
      - `createdAt` string: ISO-8601 creation timestamp. Absent for `default` catalog items, which are served from Tella's catalog rather than stored as rows.
      - `dimensions` object: Pixel dimensions, for visual media
        - `height` integer, required
        - `width` integer, required
      - `durationMs` number: Duration in milliseconds, for time-based media
      - `id` string, required: Unique library item identifier
      - `link` string: For `pinterest`, `arena` and `mymind` items: the page the pin or save links to. For `vintage` items: the film's archive page
      - `name` string, required: Display name shown in the library
      - `presetId` string: 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`.
      - `scope` 'private' | 'workspace' | 'default' | 'video' | 'pinterest' | 'arena' | 'mymind' | 'vintage', required: 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
      - `sourceId` string: 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.
      - `summary` string: For `mymind` items: mymind's AI summary of the save
      - `tags` string[]: For `mymind` items: the save's tags
      - `type` 'image' | 'video' | 'sound-effect' | 'music' | 'lut' | 'screenshot' | 'font', required: The kind of media the item holds
      - `updatedAt` string: ISO-8601 update timestamp. Absent for `default` catalog items.
      - `url` string: 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.
    - `status` 'running' | 'completed' | 'failed', required: Page and post captures are `completed` at once; video links are `running` until downloaded

## Other responses

- `202`: Video import started; poll its status
- `400`: The request was malformed or contained invalid parameters.
- `401`: Authentication is required. Provide a valid API key.
- `403`: You don't have permission to access this resource.
- `404`: The requested resource was not found.
- `409`: 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.
- `429`: You have exceeded the rate limit. Please slow down.
- `500`: An unexpected error occurred
- `501`: The requested operation is not implemented.
- `503`: A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay.

## Changes

> 65 revisions in range; 1 not diffed.

- **2026-10-20** `e6d5eb99c711`: 2 warning
  - added the new `vintage` enum value to the `import/item/allOf[#/components/schemas/LibraryItem]/scope` response property for the response status `201`
  - added the new `vintage` enum value to the `import/item/allOf[#/components/schemas/LibraryItem]/scope` response property for the response status `202`
- **2026-10-16** `6c042ab0bd1a`: 1 info
  - added the new optional request property `video`
- **2026-10-15** `ccc049a9ea13`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/library/imports/post.md)

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) - [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withchima/apis/tella-public-api/revisions/0cc3fcd307ad?raw)