Get an edit

About

Call it after the preparation is done, and before each change: every change sends the revision you read here as expectedRevision. Times come in two bases, named in each field: sourceStartSec and sourceEndSec are seconds of the source video, outputStartSec and the others are seconds of the video that comes out. A file that the API cannot use keeps its place in the edit with assetId null. To export the edit, send compositionId to create_export (POST /v1/compositions/{compositionId}/exports).

Example use

A script that edits interviews reads the timeline once the preparation is done, keeps the revision and the segment ids, and sends them in its next call to apply_timeline_operations (POST /v1/projects/{projectId}/timeline/operations).

Endpoint

GET https://api.gpt-video.com/v1/projects/{projectId}/timeline

• Scope clips:read.
• Rate limit 120 requests a minute for each key and 240 for each account, shared by every read call. See rate limits.
• No Idempotency-Key.

Parameters

Path

Request

Get an edit.

curl "https://api.gpt-video.com/v1/projects/prj_b9c1f9c7873dcef51a57/timeline" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY"

const res = await fetch("https://api.gpt-video.com/v1/projects/prj_b9c1f9c7873dcef51a57/timeline", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
  },
});
const data = await res.json();
console.log(data);

import os

import requests

r = requests.get(
    "https://api.gpt-video.com/v1/projects/prj_b9c1f9c7873dcef51a57/timeline",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
)
data = r.json()
print(data)

{
  "method": "tools/call",
  "params": {
    "name": "get_timeline",
    "arguments": {
      "projectId": "prj_b9c1f9c7873dcef51a57"
    }
  }
}

Response

A successful call answers HTTP 200. Returns a Timeline object in timeline.

Fields to check

Response example

{
  "timeline": {
    "id": "tml_bbe061171a8229f8daed",
    "projectId": "prj_b9c1f9c7873dcef51a57",
    "compositionId": "cmp_cfbdd85eaaff301fa997",
    "revision": 1,
    "durationSec": 60,
    "aspect": "9:16",
    "reframe": "off",
    "captions": {
      "enabled": true,
      "style": "bold-karaoke"
    },
    "music": null,
    "fadeInSec": 0,
    "fadeOutSec": 0,
    "clips": [
      {
        "assetId": "ast_3f9a1c7e5b2d4086a1c4",
        "title": "Interview with a founder",
        "durationSec": 1800,
        "state": "ready"
      }
    ],
    "segments": [
      {
        "id": "seg_7279fbb508f4a22e65a4",
        "assetId": "ast_3f9a1c7e5b2d4086a1c4",
        "sourceStartSec": 120,
        "sourceEndSec": 150,
        "zoom": 1,
        "muted": false,
        "volume": 1,
        "outputStartSec": 0,
        "outputEndSec": 30
      },
      {
        "id": "seg_a9dcee59c1fb9edb6751",
        "assetId": "ast_3f9a1c7e5b2d4086a1c4",
        "sourceStartSec": 300,
        "sourceEndSec": 330,
        "zoom": 1,
        "muted": false,
        "volume": 1,
        "outputStartSec": 30,
        "outputEndSec": 60
      }
    ],
    "texts": [
      {
        "id": "ovl_49f5239b9cd73496225d",
        "text": "Paid before the product",
        "preset": "headline",
        "outputStartSec": 0,
        "durationSec": 3,
        "xPercent": null,
        "yPercent": null
      }
    ],
    "broll": [
      {
        "id": "brl_f44d18e008ec4009bf10",
        "assetId": "ast_8ac5d8b97546145cdbf6",
        "outputStartSec": 12,
        "durationSec": 4,
        "fit": "cover"
      }
    ],
    "diagnostics": []
  }
}

{
  "error": {
    "code": "NOT_READY",
    "message": "This edit is still being prepared.",
    "hint": "Wait the number of seconds in the Retry-After header, then send the same request again.",
    "requestId": "req_6f1c3a8e0d5b29e74c1a6f30"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "This edit is not prepared yet. Prepare it with prepare_timeline.",
    "requestId": "req_3a9d7c1e5f0b84a26d9c3e15"
  }
}

Errors

Every call can also answer these errors. VALIDATION_FAILED, UNKNOWN_PARAMETER, UNAUTHORIZED, SCOPE_MISSING, RATE_LIMITED, INTERNAL, UNAVAILABLE.

Cost

No credits are used.

Related operations

• prepare_timeline (POST /v1/projects/{projectId}/timeline/prepare) Prepare an edit
• apply_timeline_operations (POST /v1/projects/{projectId}/timeline/operations) Change an edit
• add_timeline_clip (POST /v1/projects/{projectId}/timeline/clips) Add a video to an edit
• list_timeline_revisions (GET /v1/projects/{projectId}/timeline/revisions) List the revisions of an edit
• create_export (POST /v1/compositions/{compositionId}/exports) Export a composition
• restore_timeline (POST /v1/projects/{projectId}/timeline/restore) Restore a revision of an edit

Questions

Why is a clip in state failed?

Its video could not be prepared after several tries, and it is not prepared again by itself. Remove its segments with apply_timeline_operations (POST /v1/projects/{projectId}/timeline/operations); the rest of the edit keeps working.

Why is an assetId null?

The file no longer exists or cannot be used through the API, for example a file made in another part of the GPT-Video app. The segment, b-roll or music keeps its place in the edit.

View as Markdown