Update a project

About

Use it to choose the settings listed in missingSettings, or to change them before the next analysis. Only the fields you send change. The source video cannot be changed: sending sourceAssetId is refused, and to analyze another video you create another project. Settings changed while an analysis is waiting to start are used by that analysis; the price depends only on the source video.

Example use

A tool shows the missing settings of a project to a person, sends their choices with update_project (PATCH /v1/projects/{projectId}), and reads the project again to see that missingSettings is empty before it calls analyze_project (POST /v1/projects/{projectId}/analyze).

Endpoint

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

• 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

Body

The body is optional. Send only the fields you want to change.

Send only the fields listed here. Any other field is refused with UNKNOWN_PARAMETER.

Request

Choose the settings a draft is missing.

curl -X PATCH "https://api.gpt-video.com/v1/projects/prj_1d8b6e0c47a24f93b1c2" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "language": "en",
      "minDurationSec": 20,
      "maxDurationSec": 45,
      "captionStyle": "bold-karaoke",
      "reframe": "face"
    }
  }'

const res = await fetch("https://api.gpt-video.com/v1/projects/prj_1d8b6e0c47a24f93b1c2", {
  method: "PATCH",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "settings": {
      "language": "en",
      "minDurationSec": 20,
      "maxDurationSec": 45,
      "captionStyle": "bold-karaoke",
      "reframe": "face"
    }
  }),
});
const data = await res.json();
console.log(data);

import os

import requests

r = requests.patch(
    "https://api.gpt-video.com/v1/projects/prj_1d8b6e0c47a24f93b1c2",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
    },
    json={
        "settings": {
            "language": "en",
            "minDurationSec": 20,
            "maxDurationSec": 45,
            "captionStyle": "bold-karaoke",
            "reframe": "face"
        }
    },
)
data = r.json()
print(data)

{
  "method": "tools/call",
  "params": {
    "name": "update_project",
    "arguments": {
      "projectId": "prj_1d8b6e0c47a24f93b1c2",
      "settings": {
        "language": "en",
        "minDurationSec": 20,
        "maxDurationSec": 45,
        "captionStyle": "bold-karaoke",
        "reframe": "face"
      }
    }
  }
}

Response

A successful call answers HTTP 200. Returns a Project object in project.

Fields to check

Response example

{
  "project": {
    "id": "prj_1d8b6e0c47a24f93b1c2",
    "kind": "autoclip",
    "title": "Weekly podcast",
    "status": "draft",
    "sourceAssetId": null,
    "compositionId": null,
    "settings": {
      "language": "en",
      "clipCount": 5,
      "minDurationSec": 20,
      "maxDurationSec": 45,
      "objective": "educational",
      "captionStyle": "bold-karaoke",
      "reframe": "face",
      "instructions": null,
      "vocabulary": null
    },
    "missingSettings": [],
    "splitScreen": null,
    "streamer": null,
    "redditStory": null,
    "fakeText": null,
    "vibeEdit": null,
    "errorMessage": null,
    "createdAt": "2026-09-01T09:50:00.000Z",
    "updatedAt": "2026-09-01T11:05:00.000Z"
  }
}

{
  "title": "Founder interview, part one",
  "settings": {
    "instructions": null
  }
}

{
  "project": {
    "id": "prj_7c2e9a4f1b3d4e8096a5",
    "kind": "autoclip",
    "title": "Founder interview, part one",
    "status": "ready",
    "sourceAssetId": "ast_3f9a1c7e5b2d4086a1c4",
    "compositionId": null,
    "settings": {
      "language": "en",
      "clipCount": 3,
      "minDurationSec": 15,
      "maxDurationSec": 60,
      "objective": "viral",
      "captionStyle": "word-pop",
      "reframe": "face",
      "instructions": null,
      "vocabulary": null
    },
    "missingSettings": [],
    "splitScreen": null,
    "streamer": null,
    "redditStory": null,
    "fakeText": null,
    "vibeEdit": null,
    "errorMessage": null,
    "createdAt": "2026-09-01T09:10:00.000Z",
    "updatedAt": "2026-09-01T11:05:00.000Z"
  }
}

{
  "title": "Renamed"
}

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

Errors

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

Cost

No credits are used.

Related operations

• get_project (GET /v1/projects/{projectId}) Get a project
• estimate_analysis (POST /v1/projects/{projectId}/analyze/estimate) Estimate the credits of an analysis or a build
• analyze_project (POST /v1/projects/{projectId}/analyze) Analyze a project
• get_setting_options (GET /v1/reference/setting-options) Get the setting options
• create_project (POST /v1/projects) Create a project

Questions

How do I clear a setting?

Send null for instructions or vocabulary to remove them. The other settings cannot be cleared, only changed to another value.

Can I set minDurationSec higher than maxDurationSec?

Yes, for a moment: each change is saved as it comes, so you can raise the minimum before the maximum. analyze_project (POST /v1/projects/{projectId}/analyze) refuses while the minimum is longer than the maximum.

Why is my split screen project refused?

update_project (PATCH /v1/projects/{projectId}) changes Auto Clip projects only. Every other kind has its own operations, such as update_split_screen_project (PATCH /v1/projects/{projectId}/split-screen) for a split screen project or update_streamer_project (PATCH /v1/projects/{projectId}/streamer) for a streamer project.

View as Markdown