> ## 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. # Generate media with AI > Starts generating an image or a sound effect from a text prompt with the same AI generators the editor's media panels use. Generation is asynchronous: the response is a `generation` whose `id` is the private library item the result is saved as. Poll `GET /v1/library/generations/{id}` every few seconds (images usually take 30-90 seconds, sound effects 10-30) until `status` is `completed`, then pass `item.sourceId` anywhere a source is accepted — `POST /v1/videos/{id}/clips/{clipId}/overlays` for an image overlay, `POST /v1/videos/{id}/clips/{clipId}/layouts` with `media` for b-roll, `POST /v1/videos/{id}/clips/{clipId}/sound-effects` for a sound effect. The finished item also appears in `GET /v1/library?scope=private`. Each generation counts against the caller's weekly AI generation allowance, which depends on the plan; exceeding it answers 403 with the reset time. ## OpenAPI ````yaml /openapi.json post /v1/library/generations 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 100 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: >- Viewing analytics for a video or across the workspace: plays, watch time, retention, geography, referrers name: Analytics - 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: Webhook endpoint management name: Webhooks externalDocs: description: API versioning and deprecation policy url: https://www.tella.com/docs/versioning paths: /v1/library/generations: post: tags: - Library summary: Generate media with AI description: >- Starts generating an image or a sound effect from a text prompt with the same AI generators the editor's media panels use. Generation is asynchronous: the response is a `generation` whose `id` is the private library item the result is saved as. Poll `GET /v1/library/generations/{id}` every few seconds (images usually take 30-90 seconds, sound effects 10-30) until `status` is `completed`, then pass `item.sourceId` anywhere a source is accepted — `POST /v1/videos/{id}/clips/{clipId}/overlays` for an image overlay, `POST /v1/videos/{id}/clips/{clipId}/layouts` with `media` for b-roll, `POST /v1/videos/{id}/clips/{clipId}/sound-effects` for a sound effect. The finished item also appears in `GET /v1/library?scope=private`. Each generation counts against the caller's weekly AI generation allowance, which depends on the plan; exceeding it answers 403 with the reset time. operationId: createGeneration requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateGenerationRequest' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/CreateGenerationResponse' description: Accepted 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: CreateGenerationRequest: additionalProperties: false description: Start generating media from a prompt properties: model: description: >- For `image` only: which GPT Image 2.5 model to use. `sunburst` (default) is the most capable and follows reference images most precisely; `flare` is faster. enum: - sunburst - flare example: flare type: string prompt: description: >- What to generate. Up to 4000 characters for an image, 2000 for a sound effect. example: A watercolor illustration of a lighthouse at dawn minLength: 1 type: string referenceSourceId: description: >- For `image` only: the `sourceId` of an image source to guide the generation — from `POST /v1/sources` (`kind: "image"`) after uploading the bytes, or an `image` library item's `sourceId`. example: su_abc123def456 type: string type: $ref: '#/components/schemas/GenerationType' required: - type - prompt type: object CreateGenerationResponse: additionalProperties: false description: The generation that was started, plus the weekly allowance properties: generation: $ref: '#/components/schemas/Generation' limit: description: >- The caller's weekly AI generation allowance for this media type, which depends on the plan example: 20 maximum: 9007199254740991 minimum: -9007199254740991 type: integer remaining: description: Generations left in the current week, after this one example: 19 maximum: 9007199254740991 minimum: -9007199254740991 type: integer resetAt: description: When the weekly allowance resets, as a millisecond epoch example: 1760000000000 type: number required: - generation - limit - remaining - resetAt 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 GenerationType: description: The kind of media to generate enum: - image - sound-effect example: image type: string Generation: additionalProperties: false description: An AI media generation and, once finished, its library item properties: error: description: >- A sanitized, human-readable reason when `status` is `failed`. It may identify a content-safety rejection or timeout, or report a generic failure. Do not parse this text for machine handling. type: string id: description: >- Generation ID. It is also the ID of the private library item the result is saved as, so it can be passed to `GET /v1/library/generations/{id}` to poll and shows up in `GET /v1/library?scope=private` once finished. example: mi_abc123def456 type: string item: allOf: - $ref: '#/components/schemas/LibraryItem' description: >- The finished library item, present once `status` is `completed`. Pass its `sourceId` anywhere a source is accepted — overlays, layout media, sound effects. prompt: description: The prompt the media is being generated from example: A watercolor illustration of a lighthouse at dawn type: string status: $ref: '#/components/schemas/GenerationStatus' type: $ref: '#/components/schemas/GenerationType' required: - id - type - status - prompt 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 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, 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 GenerationStatus: description: >- `pending` and `running` mean the generator is still working — poll again in a few seconds. `completed` means `item` is ready to place. `failed` is final; start a new generation. enum: - pending - running - completed - failed example: completed type: string LibraryItemScope: description: >- Where the item lives: a library scope, `video` for an image brought into one video's library, or `pinterest`, `arena` or `mymind` for an image still in the connected service enum: - private - workspace - default - video - pinterest - arena - mymind 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](/docs/media-library-api.md) - [Add media (B-roll)](/docs/help/editing/use-media.md) - [Add text to your video](/docs/help/editing/text-overlays.md) - [AI media generation](/docs/mcp-tools/ai-media-generation.md) - [Auto-generate layouts with AI](/docs/api-reference/clips/auto-generate-layouts-with-ai.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.