> ## Documentation Index > Fetch the complete documentation index at: https://www.tella.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json post /v1/library/imports openapi: 3.0.3 info: description: >- The Tella Public API allows you to programmatically access your videos and playlists, including transcripts, chapters, and thumbnails. ## Authentication All requests require a Bearer token in the Authorization header: ``` Authorization: Bearer tella_pk_xxxxx... ``` API keys can be generated in your Tella workspace settings. ## Rate Limiting The API is rate-limited to 200 requests per minute per user within a workspace. Rate limit information is returned in response headers: - `RateLimit-Policy`: Named quota, request limit, and window in seconds - `RateLimit`: Remaining quota and seconds until reset - `X-RateLimit-Limit`: Maximum requests per window - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp in milliseconds when the window resets A `429 Too Many Requests` response also includes `Retry-After` in seconds. title: Tella Public API version: 1.0.0 servers: - description: Production url: https://api.tella.com security: [] tags: - description: Video operations name: Videos - description: Sections of a video name: Clips - description: Playlist operations name: Playlists - description: Sidebar groups for organizing playlists name: Playlist Groups - description: Tags for categorizing and filtering videos name: Tags - description: 'Tella''s editor agent, working in a video: start a chat and follow it' name: Agent chats - description: >- Viewing analytics for a video or across the workspace: plays, watch time, retention, geography, referrers name: Analytics - description: The signed-in user, their workspace, its plan and agent credits name: Account - description: Personal, workspace, and default video backgrounds name: Backgrounds - description: >- Reusable media saved to a workspace, plus Tella's curated sound effect and background music catalogs — the same items the editor's media panels show name: Library - description: >- Motion graphics documents a video plays live as a Tella Motion clip, overlay or b-roll, edited with the editor's own commands name: Tella Motion - description: >- Screen walkthroughs an agent films of a web page with no one recording. Takes are started and read over the MCP server name: Auto Capture - description: Webhook endpoint management name: Webhooks externalDocs: description: API versioning and deprecation policy url: https://www.tella.com/docs/versioning paths: /v1/library/imports: post: tags: - Library summary: Import media from a URL description: >- 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. operationId: startImport requestBody: content: application/json: schema: $ref: '#/components/schemas/StartImportRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/ImportResponse' description: Captured and saved to the library headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '202': content: application/json: schema: $ref: '#/components/schemas/ImportResponse' description: Video import started; poll its status headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '400': content: application/json: example: docsUrl: https://docs.tella.com/ error: bad_request message: The request was malformed or contained invalid parameters. schema: $ref: '#/components/schemas/ErrorResponse' description: The request was malformed or contained invalid parameters. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '401': content: application/json: example: docsUrl: https://docs.tella.com/ error: unauthorized message: Authentication is required. Provide a valid API key. schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication is required. Provide a valid API key. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '403': content: application/json: example: docsUrl: https://docs.tella.com/ error: forbidden message: You don't have permission to access this resource. schema: $ref: '#/components/schemas/ErrorResponse' description: You don't have permission to access this resource. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '404': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_found message: The requested resource was not found. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested resource was not found. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '409': content: application/json: example: 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. schema: $ref: '#/components/schemas/ErrorResponse' description: >- 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. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '429': content: application/json: example: docsUrl: https://docs.tella.com/ error: rate_limited message: You have exceeded the rate limit. Please slow down. schema: $ref: '#/components/schemas/ErrorResponse' description: You have exceeded the rate limit. Please slow down. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Retry-After: $ref: '#/components/headers/RetryAfter' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '500': content: application/json: example: docsUrl: https://docs.tella.com/ error: server_error message: An unexpected error occurred schema: $ref: '#/components/schemas/ErrorResponse' description: An unexpected error occurred headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '501': content: application/json: example: docsUrl: https://docs.tella.com/ error: not_implemented message: The requested operation is not implemented. schema: $ref: '#/components/schemas/ErrorResponse' description: The requested operation is not implemented. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' '503': content: application/json: example: 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. schema: $ref: '#/components/schemas/ErrorResponse' description: >- A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay. headers: Deprecation: $ref: '#/components/headers/Deprecation' RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimitPolicy' Sunset: $ref: '#/components/headers/Sunset' X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' security: - BearerAuth: [] components: schemas: StartImportRequest: additionalProperties: false properties: scroll: description: >- Record a scrolling web page as video instead of a still (default false). Ignored for social posts and video links. type: boolean url: description: >- 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. example: https://tella.com minLength: 1 type: string video: description: >- 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. type: boolean videoId: description: >- Save into this video's own library instead of your private library. You must be able to edit it. Required for video downloads. example: vid_abc123def456 type: string required: - url type: object ImportResponse: additionalProperties: false properties: import: $ref: '#/components/schemas/Import' required: - import type: object ErrorResponse: additionalProperties: false description: Standard error response format properties: docsUrl: description: Link to Tella API documentation example: https://docs.tella.com/ format: uri type: string error: description: Machine-readable error code enum: - bad_request - unauthorized - forbidden - not_found - rate_limited - server_error - conflict - edit_conflict - not_implemented - unavailable example: not_found type: string message: description: Human-readable error message example: Resource not found type: string required: - error - message - docsUrl type: object Import: additionalProperties: false properties: error: description: Why the import failed, set when `status` is `failed` type: string id: description: The library item the import is saved as; poll with it example: mi_abc123def456 type: string item: allOf: - $ref: '#/components/schemas/LibraryItem' description: >- 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. status: description: >- Page and post captures are `completed` at once; video links are `running` until downloaded enum: - running - completed - failed type: string required: - id - status type: object LibraryItem: additionalProperties: false description: >- A placeable piece of media — either saved to a workspace's library, or an entry in Tella's curated catalog properties: category: description: >- Catalog grouping, for `default` items only — the same grouping the editor's sound effects and background music panels show example: Everyday type: string createdAt: description: >- ISO-8601 creation timestamp. Absent for `default` catalog items, which are served from Tella's catalog rather than stored as rows. type: string dimensions: additionalProperties: false description: Pixel dimensions, for visual media properties: height: maximum: 9007199254740991 minimum: -9007199254740991 type: integer width: maximum: 9007199254740991 minimum: -9007199254740991 type: integer required: - width - height type: object durationMs: description: Duration in milliseconds, for time-based media example: 4200 type: number id: description: Unique library item identifier example: media_abc123def456 type: string link: description: >- For `pinterest`, `arena` and `mymind` items: the page the pin or save links to. For `vintage` items: the film's archive page type: string name: description: Display name shown in the library example: Intro camera take type: string presetId: description: >- 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`. example: cha-ching type: string scope: $ref: '#/components/schemas/LibraryItemScope' sourceId: description: >- 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. example: su_abc123def456 type: string summary: description: 'For `mymind` items: mymind''s AI summary of the save' type: string tags: description: 'For `mymind` items: the save''s tags' items: type: string type: array type: $ref: '#/components/schemas/LibraryItemType' updatedAt: description: ISO-8601 update timestamp. Absent for `default` catalog items. type: string url: description: >- 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. type: string required: - id - type - name - scope type: object LibraryItemScope: description: >- 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 enum: - private - workspace - default - video - pinterest - arena - mymind - vintage example: private type: string LibraryItemType: description: The kind of media the item holds enum: - image - video - sound-effect - music - lut - screenshot - font example: video type: string headers: Deprecation: description: Indicates that an API operation is deprecated, following RFC 9745 example: '@1767225600' schema: type: string RateLimit: description: >- Current quota with remaining requests (`r`) and seconds until reset (`t`) example: '"public-api";r=95;t=42' schema: type: string RateLimitPolicy: description: >- Named quota policy with the request limit (`q`) and window in seconds (`w`) example: '"public-api";q=100;w=60' schema: type: string Sunset: description: >- Indicates when a deprecated API operation will become unavailable, following RFC 8594 example: Tue, 30 Jun 2026 23:59:59 GMT schema: type: string XRateLimitLimit: description: Maximum requests allowed in the current window example: 100 schema: type: integer XRateLimitRemaining: description: Requests remaining in the current window example: 95 schema: type: integer XRateLimitReset: description: Unix timestamp in milliseconds when the window resets example: 1704067200000 schema: format: int64 type: integer RetryAfter: description: Seconds to wait before retrying a rate-limited request example: 45 schema: minimum: 1 type: integer securitySchemes: BearerAuth: description: API key obtained from your Tella account settings scheme: bearer type: http ```` ## Related topics - [Media library API](https://www.tella.com/docs/media-library-api.md) - [Library](https://www.tella.com/docs/mcp-tools/library.md) - [Get an import's status](https://www.tella.com/docs/api-reference/library/get-an-imports-status.md) - [Import a video from YouTube, X, Instagram, or TikTok](https://www.tella.com/docs/help/editing/import-a-youtube-video.md) - [Capture a web page or social post](https://www.tella.com/docs/api-reference/library/capture-a-web-page-or-social-post.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.