Overlays API

Overlays are editable timeline items that appear above video. The supported public text layer is the same layer shown in the dashboard under Combined Text > Text.

Use /content-items with kind: "overlay" for normal text. Retired overlay and generated graphics routes are not part of the public agent-facing API.

Endpoints

• GET /v1/projects/{project_id}/content-items
• POST /v1/projects/{project_id}/content-items
• PATCH /v1/projects/{project_id}/content-items/{content_item_id}
• DELETE /v1/projects/{project_id}/content-items/{content_item_id}

Add an Editable Text Overlay

curl -X POST https://www.blitzreels.com/api/v1/projects/{project_id}/content-items \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "overlay",
    "text": "5 Productivity Tips",
    "start_seconds": 0,
    "duration_seconds": 3,
    "layer_index": 1
  }'

{
  "success": true,
  "timeline_item_id": "timeline-item-uuid",
  "content_item_id": "content-item-uuid",
  "playground_composition_id": "overlay-renderer-uuid",
  "watermark_id": null
}

List and Edit Overlays

curl https://www.blitzreels.com/api/v1/projects/{project_id}/content-items \
  -H "Authorization: Bearer $BLITZREELS_API_KEY"

Use the returned timeline_item_id with Timeline API routes for timing and placement:

• POST /v1/projects/{project_id}/timeline/move
• POST /v1/projects/{project_id}/timeline/transform
• POST /v1/projects/{project_id}/timeline/batch-transform

Update metadata or delete the overlay:

curl -X PATCH https://www.blitzreels.com/api/v1/projects/{project_id}/content-items/{content_item_id} \
  -H "Authorization: Bearer $BLITZREELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Opening hook" }'

curl -X DELETE https://www.blitzreels.com/api/v1/projects/{project_id}/content-items/{content_item_id} \
  -H "Authorization: Bearer $BLITZREELS_API_KEY"

Placement Tips

• Keep overlays on higher layers so they stay visible above B-roll.
• Use Timeline API move/transform routes after creation for exact placement.
• Preview frames before export when overlays sit near captions or platform safe zones.

Related

• Timeline Editing API
• Captions API
• Backgrounds API