Get a clip

get_clipGET/v1/clips/{clipId}Beta

Returns one clip with its place in the source video, its score and the copy suggested for posting it.

Beta. This endpoint is supported and can gain new fields. If a change would break your code, we tell you before it takes effect and list it in the changelog.

About

Use it to read a clip again after list_clips (GET /v1/projects/{projectId}/clips), for example to check its status before you accept or reject it. Analyzing the project again removes the proposed and rejected clips, so their ids then answer NOT_FOUND; accepted clips are kept with their ids.

Example use

A review tool shows one clip in a detail view. Before it sends the accept or the reject, it reads the clip again and checks its status, in case a colleague decided on it in the meantime.

Endpoint

Code

GET https://api.gpt-video.com/v1/clips/{clipId}

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

Name	Type	Required	Description
`clipId`	string	Required	The id of the clip, as list_clips (`GET /v1/projects/{projectId}/clips`) returns it. Matches `^cnd_[0-9a-f]{20}$`.

Request

Get a clip.

curl

curl "https://api.gpt-video.com/v1/clips/cnd_2b7f4e91a0c84d35e6f0" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY"

TypeScript

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

Python

import os

import requests

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

MCP (Full)

{
  "method": "tools/call",
  "params": {
    "name": "get_clip",
    "arguments": {
      "clipId": "cnd_2b7f4e91a0c84d35e6f0"
    }
  }
}

Response

A successful call answers HTTP 200. Returns a Clip object in clip.

Fields to check

Name	Type	Description
`clip.id`	string	The clip id. It starts with cnd_.
`clip.status`	string	proposed is waiting for a decision, accepted has a composition, rejected was set aside and can be restored.

Response example

HTTP 200

{
  "clip": {
    "id": "cnd_2b7f4e91a0c84d35e6f0",
    "projectId": "prj_7c2e9a4f1b3d4e8096a5",
    "sourceAssetId": "ast_3f9a1c7e5b2d4086a1c4",
    "summary": "The founder explains how the first customer paid before the product existed.",
    "reason": "A clear claim in the first seconds and a result at the end.",
    "tags": [
      "startups",
      "sales"
    ],
    "createdAt": "2026-09-01T09:40:00.000Z",
    "status": "proposed",
    "rank": 1,
    "startSec": 300,
    "endSec": 330,
    "durationSec": 30,
    "title": "The first customer",
    "hook": "Our first customer changed everything",
    "score": 81,
    "scoreBreakdown": [
      {
        "factor": "hook",
        "label": "Hook (first 3 seconds)",
        "score": 8,
        "note": "Opens on a concrete claim."
      },
      {
        "factor": "payoff",
        "label": "Payoff / ending",
        "score": 7,
        "note": "Ends on the result."
      },
      {
        "factor": "clarity",
        "label": "Clarity",
        "score": 6,
        "note": "One idea, said plainly."
      },
      {
        "factor": "emotion",
        "label": "Emotion",
        "score": 8,
        "note": "The speaker sounds surprised."
      },
      {
        "factor": "novelty",
        "label": "Novelty / surprise",
        "score": 7,
        "note": "Not the usual advice."
      },
      {
        "factor": "selfContained",
        "label": "Self-contained",
        "score": 6,
        "note": "Needs no context."
      },
      {
        "factor": "quotability",
        "label": "Quotability",
        "score": 8,
        "note": "Has a line people repeat."
      },
      {
        "factor": "dialogue",
        "label": "Dialogue (back-and-forth)",
        "score": 7,
        "note": "A single speaker."
      }
    ],
    "transcriptExcerpt": "before we had a product and that changed everything for our team the first customer paid us before we had a product and that changed everything for our team the first customer paid us before we had a product and that changed everything for our team the first customer paid us before we had a product and that changed everything for our team the first customer paid us before we had a product and that",
    "social": {
      "title": "The first customer",
      "caption": "How a first customer paid before there was a product.",
      "hashtags": [
        "#startup",
        "#founder"
      ]
    },
    "compositionId": null
  }
}

All response fields

Name	Type	Required	Description
`clip`	Clip object	Required	Described in Clip object.

More examples

A clip that does not exist

GET /v1/clips/cnd_4c8e0a2f6d1b49e7a3c5

HTTP 404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Clip cnd_4c8e0a2f6d1b49e7a3c5 not found",
    "hint": "Check the id. An id that belongs to another account is not found either.",
    "requestId": "req_2c9f4a1e7b0d43c58e6a1f20"
  }
}

Errors

Code	Status	When	What to do
`NOT_FOUND`	404	A clip that does not exist	Change the request, then send it again.

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

Cost

No credits are used.

list_clips (GET /v1/projects/{projectId}/clips) List the clips of a project
accept_clip (POST /v1/clips/{clipId}/accept) Accept a clip
reject_clip (POST /v1/clips/{clipId}/reject) Reject a clip
delete_composition (DELETE /v1/compositions/{compositionId}) Delete a composition

Questions

Why does a clip I listed before answer NOT_FOUND now?

The project was analyzed again, and the new analysis replaced the proposed and rejected clips with new ones. List the clips again to get their new ids.

Does reading a clip use credits?

No. Reading a clip uses no credits; it counts as one read against the rate limit of the key.

View as Markdown