API reference

Base URL and keys

• Base URL https://api.gpt-video.com/v1
• Authentication: send Authorization: Bearer <API key>. Keys start with gvk_.
• A person creates the key in the GPT-Video app at /app/developers, with the scopes clips:read, clips:write and spend. Call get_me (GET /v1/me) first to check the scopes.
• OpenAPI 3.1 https://api.gpt-video.com/v1/openapi.json

Do not assume endpoints have parameters other than the ones explicitly specified. An unknown parameter is refused with UNKNOWN_PARAMETER.

Decide by error.code, never by the HTTP status. A 429 can mean wait a minute or stop until tomorrow.

Conventions

GPT-Video turns long videos into short vertical clips. This is its REST API.

Authenticate every request with an API key: Authorization: Bearer gvk_.... Keys are created in the GPT-Video app.

Errors share one body, { "error": { "code", "message", "hint", "requestId", "details" } }. The code says what to do next; the HTTP status is only its class.

Send the same request again only after a code listed in x-retryable, after the seconds in Retry-After when the answer has it, and with the same Idempotency-Key.

A POST that spends (credits, or an export from the daily allowance) needs an Idempotency-Key header; retrying with the same key never spends twice.

x-scope is the scope an API key needs for an operation. When it needs more than one, x-scopes lists all of them. x-bonus-credits is the number of API bonus credits an operation uses when the API bonus pays for it, besides its daily allowance. An operation that spends credits uses the same number of API bonus credits when the API bonus pays for it.

Webhooks send events to an address you add on the Developers page of the GPT-Video app, at /app/developers, signed as Standard Webhooks describes. An event tells you that something changed. Call get_job (GET /v1/jobs/{jobId}) or get_export (GET /v1/exports/{exportId}) to read its current state.

Errors

A 503 UNAVAILABLE with details.reason: "switched_off" means the operation is turned off. Do not send it again. Without that reason, try at most three times. All errors lists what each code means.

IDs

IDs on the objects page lists the operations that return each kind of id and the ones that take it.

Idempotency

Create one Idempotency-Key for each request that spends credits, before you send it. If the request fails or times out, send it again with the same key. A new key is a new charge. Make the key random, such as a UUID, and never a name like upload-1: a key the API has seen before, even in an earlier task, gets that earlier answer back.

Wait and download

1. GET /v1/jobs/{jobId}?wait=25 until job.status is done, failed or cancelled.
2. If the answer comes back at once while the job is still running, wait 5 seconds before you read it again.
3. At most 10 requests with wait can be open at once for each account.
4. Follow an export the same way with GET /v1/exports/{exportId}?wait=25.
5. Download export.downloadUrl without the Authorization header. The link points to the GPT-Video website, so do not send your key to it. It works for 15 minutes.
6. For a new link, read the export again with get_export (GET /v1/exports/{exportId}). Save the file as soon as you download it.

Upload

1. create_upload (POST /v1/uploads) opens an upload and says how many parts to send and how big each one is.
2. upload_part (PUT /v1/uploads/{uploadId}/parts/{partNumber}) sends each part as raw bytes, in any order.
3. complete_upload (POST /v1/uploads/{uploadId}/complete) turns the parts into an asset that a project can use.

Upload a video file has the whole loop in code.

Using the API bonus

API bonus: 50 credits. No card needed.

• get_credits (GET /v1/credits) tells you in bonus.status whether the account has the bonus now.
• API bonus credits can be spent only through the API. They expire 30 days after you get them.
• While the bonus pays, an account can make 5 exports a day, each up to 600 seconds long. A longer export answers PLAN_REQUIRED.
• The bonus runs 1 job at a time. The next one waits with status queued.
• A daily limit answers DAILY_LIMIT_REACHED. Do not send the request again until 00:00 UTC.
• After the API bonus, the API needs a Creator or Studio plan.

MCP and REST names

MCP tool names and REST operation ids are different things. Five names exist in both, and they take different input.

A full run

From a video file on your computer to a downloaded clip. Each step uses an id that the step before it returned.

1. create_upload POST /v1/uploads. Open an upload for the video file with filename, sizeBytes and contentType. The answer says how many parts to send.
2. upload_part PUT /v1/uploads/{uploadId}/parts/{partNumber}. Send each part as raw bytes.
3. complete_upload POST /v1/uploads/{uploadId}/complete. Turn the upload into an asset. Keep asset.id.
4. create_project POST /v1/projects. Create a project with that id as sourceAssetId. Keep project.id.
5. update_project PATCH /v1/projects/{projectId}. Choose the settings that project.missingSettings lists, with the values that get_setting_options (GET /v1/reference/setting-options) returns.
6. estimate_analysis POST /v1/projects/{projectId}/analyze/estimate. Check what the analysis will cost.
7. analyze_project POST /v1/projects/{projectId}/analyze. Start the analysis with an Idempotency-Key. Keep job.id.
8. get_job GET /v1/jobs/{jobId}. Read the job with ?wait=25 until job.status is final.
9. list_clips GET /v1/projects/{projectId}/clips. List the clips the analysis proposes.
10. accept_clip POST /v1/clips/{clipId}/accept. Accept a clip. Keep composition.id.
11. create_export POST /v1/compositions/{compositionId}/exports. Export the composition with an Idempotency-Key. Keep export.id.
12. get_export GET /v1/exports/{exportId}. Read the export with ?wait=25 until it is done, then download export.downloadUrl.

Endpoints

Account and credits

• get_me GET /v1/me. Returns the API key in use, its scopes and the plan of the account it belongs to. Scope clips:read.
• get_credits GET /v1/credits. Returns the credits the account can spend now, split between this month's plan credits and the top-up, the API bonus, and today's daily limits. Scope clips:read.
• list_ledger_entries GET /v1/credits/ledger. Lists every movement of the spendable credit balance and of the API bonus, newest first: charges, refunds, top-ups and corrections. Scope clips:read.

Uploads

• create_upload POST /v1/uploads. Opens an upload for a video file and says how many parts to send and how big each one is. Scope clips:write.
• upload_part PUT /v1/uploads/{uploadId}/parts/{partNumber}. Sends one part of an upload as raw bytes, and returns the parts received so far. Scope clips:write.
• get_upload GET /v1/uploads/{uploadId}. Returns an open upload with the parts that arrived and the time it expires. Scope clips:read.
• complete_upload POST /v1/uploads/{uploadId}/complete. Turns an upload whose parts all arrived into an asset that a project can use as its source. Scope clips:write.
• cancel_upload DELETE /v1/uploads/{uploadId}. Cancels an open upload and deletes the parts sent so far. Scope clips:write.

Videos and transcripts

• list_assets GET /v1/assets. Lists the videos you uploaded or imported, newest first, a page at a time. Scope clips:read.
• get_asset GET /v1/assets/{assetId}. Returns one file: a video you uploaded, its converted copy, or the file of an export. Scope clips:read.
• get_transcript GET /v1/assets/{assetId}/transcript. Returns the words of a video with their times, as speech recognition heard them. Scope clips:read.

Projects and analysis

• list_projects GET /v1/projects. Returns the projects of the account, the most recently created first, one page at a time. Scope clips:read.
• create_project POST /v1/projects. Creates an Auto Clip project on a video you uploaded, with the settings you choose. Scope clips:write.
• get_project GET /v1/projects/{projectId}. Returns one project with its status, settings, missing settings and the analysis running on it. Scope clips:read.
• update_project PATCH /v1/projects/{projectId}. Renames an Auto Clip project or changes its settings, leaving every field you do not send as it was. Scope clips:write.
• analyze_project POST /v1/projects/{projectId}/analyze. Starts the analysis that transcribes the source video and finds its clips, and returns the job to follow. Scope spend.
• estimate_analysis POST /v1/projects/{projectId}/analyze/estimate. Estimate the credits of an analysis, a build or the preparation of an edit, and who would pay them, without starting anything. Scope clips:read.

Clips

• list_clips GET /v1/projects/{projectId}/clips. Returns the clips an analysis found in a project, in the order the analysis ranked them. Scope clips:read.
• get_clip GET /v1/clips/{clipId}. Returns one clip with its place in the source video, its score and the copy suggested for posting it. Scope clips:read.
• accept_clip POST /v1/clips/{clipId}/accept. Accepts a clip and returns the composition made from it, the vertical video you can export. Scope clips:write.
• reject_clip POST /v1/clips/{clipId}/reject. Sets a proposed clip aside, so it no longer counts among the clips waiting for a decision. Scope clips:write.
• restore_clip POST /v1/clips/{clipId}/restore. Brings a rejected clip back among the proposed clips, with the same id. Scope clips:write.

Compositions and captions

• get_composition GET /v1/compositions/{compositionId}. Returns a composition: the vertical video made from a clip, with its size, captions, hook and framing. Scope clips:read.
• get_composition_captions GET /v1/compositions/{compositionId}/captions. Returns the captions of a composition as an SRT or WebVTT file, inside a JSON answer. Scope clips:read.
• list_compositions GET /v1/projects/{projectId}/compositions. Lists the compositions of a project, the newest first, a page at a time. Scope clips:read.
• edit_composition POST /v1/compositions/{compositionId}/edit. Changes the title, hook, captions, start and end, or music volume of a composition. Scope clips:write.
• replace_caption_words POST /v1/compositions/{compositionId}/captions/replace. Replaces words in the captions of a composition, such as a name the transcript got wrong. Scope clips:write.
• reframe_composition POST /v1/compositions/{compositionId}/reframe. Computes the vertical framing of a composition again, following the face or keeping the center. Scope clips:write.
• delete_composition DELETE /v1/compositions/{compositionId}. Deletes the composition of an Auto Clip clip, and the clip goes back to proposed. Scope clips:write.

Exports

• create_export POST /v1/compositions/{compositionId}/exports. Starts rendering a composition to an MP4 file and returns the export to follow. Scope spend.
• get_export GET /v1/exports/{exportId}. Returns an export: its status, its file and, once it is done, a fresh download link. Scope clips:read.
• list_exports GET /v1/projects/{projectId}/exports. Lists the exports of a project, newest first, optionally of one composition only. Scope clips:read.

Formats

• create_split_screen_project POST /v1/projects/split-screen. Creates a split screen project from two videos you uploaded: the main video on top and a background video under it. Scope clips:write.
• update_split_screen_project PATCH /v1/projects/{projectId}/split-screen. Changes the name, the layout, the captions, the start of the background or the vocabulary of a split screen project. Scope clips:write.
• build_split_screen_video POST /v1/projects/{projectId}/split-screen/build. Starts the build of the video of a split screen project, and returns the job to follow. Scope spend.
• create_streamer_project POST /v1/projects/streamer. Creates a streamer project from a clip you uploaded: a vertical video that follows the speaker, with a headline and captions. Scope clips:write.
• update_streamer_project PATCH /v1/projects/{projectId}/streamer. Changes the name, the headline, the captions, the framing or the vocabulary of a streamer project. Scope clips:write.
• build_streamer_video POST /v1/projects/{projectId}/streamer/build. Starts the build of the vertical video of a streamer project, and returns the job to follow. Scope spend.
• create_reddit_story_project POST /v1/projects/reddit-story. Creates a Reddit story project: a post read by a synthetic voice over a background video, with a title card and captions. Scope clips:write.
• update_reddit_story_project PATCH /v1/projects/{projectId}/reddit-story. Changes the post, the voice, the language, the captions or the background video of a Reddit story project. Scope clips:write.
• build_reddit_story_video POST /v1/projects/{projectId}/reddit-story/build. Starts the build of the video of a Reddit story project, with its synthetic voice, and returns the job to follow. Scope spend.
• create_fake_text_project POST /v1/projects/fake-text. Creates a fake text project, a chat story shown as a vertical video, with its look, language, voices and background chosen now. Scope clips:write.
• update_fake_text_project PATCH /v1/projects/{projectId}/fake-text. Changes the name, look, language, voices setting or background of a fake text project, leaving every field you do not send as it was. Scope clips:write.
• get_fake_text_story GET /v1/projects/{projectId}/story. Returns the story of a fake text project, line by line, with the voice of each side and which lines have their voice. Scope clips:read.
• update_fake_text_story PUT /v1/projects/{projectId}/story. Replaces the story of a fake text project with the one you send, or writes its first story, and rebuilds its video. Scope clips:write.
• generate_fake_text_story POST /v1/projects/{projectId}/story/generate. Starts writing a new story for a fake text project from your brief, and returns the job to follow. Scope spend.
• create_fake_text_voices POST /v1/projects/{projectId}/story/voices. Starts making the voice of every line of the story that does not have it yet, and returns the job to follow. Scope spend.

Tools

• create_voiceover POST /v1/voiceovers. Starts reading a script aloud with a synthetic voice, and returns the tool run that makes the audio file. Scope spend.
• separate_audio POST /v1/audio-separations. Starts splitting the sound of a video into its voices or everything else, and returns the tool run that makes the audio file. Scope spend.
• brainstorm_ideas POST /v1/brainstorms. Starts writing ideas for short videos on a topic, and returns the tool run that holds them once it is done. Scope spend.
• get_tool_run GET /v1/tool-runs/{toolRunId}. Returns a tool run: its status and, once it is done, its audio file with a fresh download link, or its ideas. Scope clips:read.
• list_tool_runs GET /v1/tool-runs. Lists the voiceovers, audio separations and brainstorms of the account, newest first. Scope clips:read.

Timeline editing

• create_vibe_edit_project POST /v1/projects/vibe-edit. Creates a Vibe Editing project from a video you uploaded: an edit of the whole video that you change with timeline operations. Scope clips:write.
• prepare_timeline POST /v1/projects/{projectId}/timeline/prepare. Starts the preparation of a Vibe Editing project: the video is transcribed and analyzed once, and the edit is built from it. Scope spend.
• get_timeline GET /v1/projects/{projectId}/timeline. Returns the edit of a prepared Vibe Editing project: its videos, segments, texts, b-roll, captions and revision. Scope clips:read.
• apply_timeline_operations POST /v1/projects/{projectId}/timeline/operations. Applies a list of operations to an edit in one change: cuts, order, transitions, zoom, sound, captions, texts, b-roll, music and shape. Scope clips:write.
• add_timeline_clip POST /v1/projects/{projectId}/timeline/clips. Adds another video you uploaded to a prepared edit, as one segment of its whole length, and charges it once. Scope spend.
• list_timeline_revisions GET /v1/projects/{projectId}/timeline/revisions. Lists the revisions of an edit that can be restored, newest first, with who wrote each one and what it did. Scope clips:read.
• restore_timeline POST /v1/projects/{projectId}/timeline/restore. Brings an edit back to a revision listed by list_timeline_revisions (GET /v1/projects/{projectId}/timeline/revisions), as a new revision. Scope clips:write.

Editor Assistant

• create_assistant_turn POST /v1/projects/{projectId}/assistant/turns. Asks the Editor Assistant to change a project in plain words, and returns the turn that does it. Scope spend, clips:write.
• get_assistant_turn GET /v1/assistant/turns/{turnId}. Returns a turn of the Editor Assistant: its status, its reply and the actions it took. Scope clips:read.
• list_assistant_turns GET /v1/projects/{projectId}/assistant/turns. Lists the turns of the Editor Assistant on a project, newest first, the ones sent from the app included. Scope clips:read.
• undo_assistant_action POST /v1/assistant/turns/{turnId}/actions/{actionId}/undo. Puts the project back as it was before one action of a turn, and returns the turn. Scope clips:write.

Jobs

• get_job GET /v1/jobs/{jobId}. Returns a job that another call started: its kind, status and progress. Scope clips:read.

Settings and voice list

• get_setting_options GET /v1/reference/setting-options. Returns the values the settings of a project or a brainstorm accept, with a name and a description for every choice. Scope clips:read.
• list_voices GET /v1/reference/voices. Lists the synthetic voices of a language that a voiceover can use. Scope clips:read.