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 body

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

{
  "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

Changed in 3 of the 19 revisions of this API.101

Sep 28, 2026ac47c99c144f9See the full diff
- ●
  added the new edit_conflict enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new edit_conflict enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new edit_conflict enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new edit_conflict enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new edit_conflict enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new edit_conflict enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new edit_conflict enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new edit_conflict enum value to the response property for the response status
  response-property-enum-value-added
- ●
  added the new edit_conflict enum value to the response property for the response status
  response-property-enum-value-added
Sep 19, 202664764729bd601See the full diff
- ●
  added the new screenshot enum value to the ////// response property for the response status
  response-property-enum-value-added
Sep 10, 20262740bcedaa3b1See the full diff
- ○
  endpoint added
  endpoint-added

Of the 19 revisions, 1 has no diff computed.

Full history