Library

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.

post/v1/library/generations

Request

  • Base URL: https://api.tella.com
  • URL: https://api.tella.com/v1/library/generations
  • Auth: HTTP bearer

Request body

model'sunburst' | 'flare'

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.

promptstring required

What to generate. Up to 4000 characters for an image, 2000 for a sound effect.

referenceSourceIdstring

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.

type'image' | 'sound-effect' required

The kind of media to generate

Example request

{
  "model": "flare",
  "prompt": "A watercolor illustration of a lighthouse at dawn",
  "referenceSourceId": "su_abc123def456",
  "type": "image"
}

Response

Accepted

limitinteger required

The caller's weekly AI generation allowance for this media type, which depends on the plan

remaininginteger required

Generations left in the current week, after this one

resetAtnumber required

When the weekly allowance resets, as a millisecond epoch

Example response

{
  "generation": {
    "id": "mi_abc123def456",
    "item": {
      "category": "Everyday",
      "durationMs": 4200,
      "id": "media_abc123def456",
      "name": "Intro camera take",
      "presetId": "cha-ching",
      "scope": "private",
      "sourceId": "su_abc123def456",
      "type": "video"
    },
    "prompt": "A watercolor illustration of a lighthouse at dawn",
    "status": "completed",
    "type": "image"
  },
  "limit": 20,
  "remaining": 19,
  "resetAt": 1760000000000
}

Changes

No recorded changes to this operation across all 1 revision of this API.