Accept a clip

accept_clipPOST/v1/clips/{clipId}/acceptBeta

Accepts a clip and returns the composition made from it, the vertical video you can export.

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

Accepting turns the clip into a composition: the vertical video cut from the source, with captions and the hook. It uses no credits. Accepting a clip that is already accepted returns its composition again, so a retry is safe; a rejected clip can be accepted too. The framing is computed after the accept: until it is done the composition shows framing.status tracking with the job in framing.jobId, and create_export (POST /v1/compositions/{compositionId}/exports) answers NOT_READY. Follow it with get_composition (GET /v1/compositions/{compositionId}). Works on clips of Auto Clip projects only.

Example use

An editor approves a clip in a review tool, and the tool calls this to get the vertical video. It then follows the framing with get_composition (GET /v1/compositions/{compositionId}) and starts an export when the framing is done.

Endpoint

Code

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

Scope clips:write.
Rate limit 60 requests a minute for each key and 120 for each account, shared by every write call. See rate limits.
Idempotency-Key is optional.

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}$`.

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	Optional	Send the same key on every retry of this request. From 1 to 255 visible characters, such as a UUID. See idempotency.

Request

Accept a proposed clip.

curl

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

TypeScript

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

Python

import os

import requests

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

MCP (Full)

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

Response

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

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.
`composition.id`	string	The composition id. It starts with cmp_.
`composition.framing.status`	string
`composition.framing.jobId`	string or null

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": "accepted",
    "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": "cmp_b18e4f2a6c0d4973e5a1"
  },
  "composition": {
    "id": "cmp_b18e4f2a6c0d4973e5a1",
    "projectId": "prj_7c2e9a4f1b3d4e8096a5",
    "clipId": "cnd_2b7f4e91a0c84d35e6f0",
    "kind": "autoclip",
    "title": "The first customer",
    "revision": 0,
    "durationSec": 30,
    "width": 1080,
    "height": 1920,
    "fps": 30,
    "source": {
      "assetId": "ast_3f9a1c7e5b2d4086a1c4",
      "startSec": 300,
      "endSec": 330
    },
    "hook": "Our first customer changed everything",
    "captions": {
      "style": "word-pop",
      "wordCount": 75
    },
    "framing": {
      "status": "tracking",
      "jobId": "job_4f0a9c2e7d1b4e3a86c5"
    },
    "createdAt": "2026-09-01T10:30:00.000Z",
    "updatedAt": "2026-09-01T10:30:00.000Z"
  }
}

All response fields

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

More examples

Accept a clip that is already accepted

POST /v1/clips/cnd_9e04a6c3d12b4f78a5b9/accept

HTTP 200

{
  "clip": {
    "id": "cnd_9e04a6c3d12b4f78a5b9",
    "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": "accepted",
    "rank": 0,
    "startSec": 120,
    "endSec": 150,
    "durationSec": 30,
    "title": "Paid before the product",
    "hook": "They paid us before we had a product",
    "score": 87.5,
    "scoreBreakdown": [
      {
        "factor": "hook",
        "label": "Hook (first 3 seconds)",
        "score": 9,
        "note": "Opens on a concrete claim."
      },
      {
        "factor": "payoff",
        "label": "Payoff / ending",
        "score": 8,
        "note": "Ends on the result."
      },
      {
        "factor": "clarity",
        "label": "Clarity",
        "score": 7,
        "note": "One idea, said plainly."
      },
      {
        "factor": "emotion",
        "label": "Emotion",
        "score": 9,
        "note": "The speaker sounds surprised."
      },
      {
        "factor": "novelty",
        "label": "Novelty / surprise",
        "score": 8,
        "note": "Not the usual advice."
      },
      {
        "factor": "selfContained",
        "label": "Self-contained",
        "score": 7,
        "note": "Needs no context."
      },
      {
        "factor": "quotability",
        "label": "Quotability",
        "score": 9,
        "note": "Has a line people repeat."
      },
      {
        "factor": "dialogue",
        "label": "Dialogue (back-and-forth)",
        "score": 8,
        "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": "Paid before the product",
      "caption": "How a first customer paid before there was a product.",
      "hashtags": [
        "#startup",
        "#founder"
      ]
    },
    "compositionId": "cmp_4e8c2a6f09d14b73a1e5"
  },
  "composition": {
    "id": "cmp_4e8c2a6f09d14b73a1e5",
    "projectId": "prj_7c2e9a4f1b3d4e8096a5",
    "clipId": "cnd_9e04a6c3d12b4f78a5b9",
    "kind": "autoclip",
    "title": "Paid before the product",
    "revision": 0,
    "durationSec": 30,
    "width": 1080,
    "height": 1920,
    "fps": 30,
    "source": {
      "assetId": "ast_3f9a1c7e5b2d4086a1c4",
      "startSec": 120,
      "endSec": 150
    },
    "hook": "They paid us before we had a product",
    "captions": {
      "style": "word-pop",
      "wordCount": 75
    },
    "framing": {
      "status": "centered",
      "jobId": null
    },
    "createdAt": "2026-09-01T10:00:00.000Z",
    "updatedAt": "2026-09-01T10:00:00.000Z"
  }
}

Errors

Code	Status	When	What to do
`NOT_FOUND`	404	See the error reference.	Change the request, then send it again.
`CONFLICT`	409	The clip is not from an Auto Clip project, its source video no longer exists, or a setting of the project was removed after the analysis. The message says which one.	Read the resource again, then decide. Do not send the same request again.

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

Cost

No credits are used. The export of the composition uses the daily export allowance.

list_clips (GET /v1/projects/{projectId}/clips) List the clips of a project
get_clip (GET /v1/clips/{clipId}) Get a clip
reject_clip (POST /v1/clips/{clipId}/reject) Reject a clip
get_composition (GET /v1/compositions/{compositionId}) Get a composition
create_export (POST /v1/compositions/{compositionId}/exports) Export a composition
delete_composition (DELETE /v1/compositions/{compositionId}) Delete a composition

Questions

Can I accept the same clip twice?

Yes. The second accept changes nothing and returns the same composition, so a retry after a network error is safe.

Why does create_export answer NOT_READY right after an accept?

The framing of the clip is computed after the accept. Wait until get_composition (GET /v1/compositions/{compositionId}) shows a framing status other than tracking, then export.

Does accepting a clip use credits?

No. The analysis already paid for the clips. Exporting the composition uses one export of the daily allowance of the plan.

View as Markdown