Skip to content
GPT-Video
Log in
Founding offerFirst month $49 $19 + 3 bonus guides, free ($93 value)Claim it
Create a key

Paste a key to use it in the examples on these pages. The key stays in this browser tab. These pages never send it anywhere.

Delete a composition

delete_compositionDELETE/v1/compositions/{compositionId}Beta

Deletes the composition of an Auto Clip clip, and the clip goes back to proposed.

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 undo an accept_clip (POST /v1/clips/{clipId}/accept): the composition goes away and its clip is proposed again, ready to be accepted later as a new composition. Exports of a deleted composition can no longer be read; download them first. A composition that is being exported is refused until the export finishes. A DELETE sent again after a timeout answers NOT_FOUND when the first one went through: read the clip with get_clip (GET /v1/clips/{clipId}) to know. Works on compositions of Auto Clip clips only.

Example use

An editor decides that an accepted clip is not worth posting after all. The tool deletes its composition, and the clip returns to the list of clips to review, where someone else can still pick it.

Endpoint

Code
DELETE https://api.gpt-video.com/v1/compositions/{compositionId}
  • 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.
  • No Idempotency-Key.

Parameters

Path

NameTypeRequiredDescription
compositionIdstringRequiredThe id of the composition: accept_clip (POST /v1/clips/{clipId}/accept) returns it for a clip, and list_compositions (GET /v1/projects/{projectId}/compositions) or the project's compositionId give it for the other kinds of project. Matches ^cmp_[0-9a-f]{20}$.

Request

Delete the composition of a clip.

Request example
curl -X DELETE "https://api.gpt-video.com/v1/compositions/cmp_1e710123e428fb030a18" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY"
const res = await fetch("https://api.gpt-video.com/v1/compositions/cmp_1e710123e428fb030a18", {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
  },
});
const data = await res.json();
console.log(data);
import os

import requests

r = requests.delete(
    "https://api.gpt-video.com/v1/compositions/cmp_1e710123e428fb030a18",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
)
data = r.json()
print(data)
{
  "method": "tools/call",
  "params": {
    "name": "delete_composition",
    "arguments": {
      "compositionId": "cmp_1e710123e428fb030a18"
    }
  }
}

Response

A successful call answers HTTP 200.

Fields to check

NameTypeDescription
clip.idstringThe clip id. It starts with cnd_.
clip.statusstringproposed is waiting for a decision, accepted has a composition, rejected was set aside and can be restored.

Response example

HTTP 200
{
  "compositionId": "cmp_1e710123e428fb030a18",
  "deleted": true,
  "clip": {
    "id": "cnd_8e77645e55cc8ea02336",
    "projectId": "prj_7c2e9a4f1b3d4e8096a5",
    "sourceAssetId": "ast_3f9a1c7e5b2d4086a1c4",
    "status": "proposed",
    "rank": 3,
    "startSec": 900,
    "endSec": 935,
    "durationSec": 35,
    "title": "Selling the idea first",
    "hook": "Sell it before you build it",
    "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.",
    "score": 78,
    "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."
      }
    ],
    "tags": [
      "startups",
      "sales"
    ],
    "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 changed everything for our team the first customer paid us before we had",
    "social": {
      "title": "Selling the idea first",
      "caption": "How a first customer paid before there was a product.",
      "hashtags": [
        "#startup",
        "#founder"
      ]
    },
    "compositionId": null,
    "createdAt": "2026-09-01T09:40:00.000Z"
  }
}
All response fields
NameTypeRequiredDescription
compositionIdstringRequiredThe id of the composition that was deleted.
deletedbooleanRequiredAlways true.
clipClip objectRequiredThe clip of the composition, proposed again. Described in Clip object.
More examples

A composition that is being exported

DELETE /v1/compositions/cmp_1e710123e428fb030a18

HTTP 409
{
  "error": {
    "code": "CONFLICT",
    "message": "This composition is being exported. Wait for the export to finish, then delete it.",
    "requestId": "req_8d3f1b6e4a0c42d9b7e5a1c3"
  }
}

A composition that is not from an Auto Clip clip

DELETE /v1/compositions/cmp_cc26cb47fd6004aa5fba

HTTP 409
{
  "error": {
    "code": "CONFLICT",
    "message": "Only the compositions of Auto Clip clips can be deleted through the API.",
    "requestId": "req_4c0e8a2d6f1b43e7a9c5d3b1"
  }
}

Delete a composition that does not exist

DELETE /v1/compositions/cmp_7a1f5d3c9e0b42d8f6a2

HTTP 404
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Composition cmp_7a1f5d3c9e0b42d8f6a2 not found",
    "hint": "Check the id. An id that belongs to another account is not found either.",
    "requestId": "req_6b2d9f0e4a7c41b3d8e5a2f9"
  }
}

Errors

CodeStatusWhenWhat to do
NOT_FOUND404Delete a composition that does not existChange the request, then send it again.
CONFLICT409A composition that is being exportedRead 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, RATE_LIMITED, INTERNAL, UNAVAILABLE.

Cost

No credits are used.

Related operations

  • accept_clip (POST /v1/clips/{clipId}/accept) Accept a clip
  • get_clip (GET /v1/clips/{clipId}) Get a clip
  • list_compositions (GET /v1/projects/{projectId}/compositions) List the compositions of a project
  • get_export (GET /v1/exports/{exportId}) Get an export

Questions

What happens to the exports of a deleted composition?

They can no longer be read through the API, and get_export (GET /v1/exports/{exportId}) answers NOT_FOUND. Download the files you need before you delete the composition.

Can I delete the composition of a split screen or Vibe Editing project?

No. Those projects have one composition, made by their build or preparation, and it goes away only with the project, in the GPT-Video app.

View as Markdown