# GPT-Video API
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 https://www.gpt-video.com/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.

The GPT-Video API turns a long video into short vertical clips, edits timelines, makes captions and exports files over HTTPS. This page gives the conventions every call shares, the error codes and the id prefixes. At the end it lists every endpoint by group, with a link to its page.

The API is in beta. Every 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](https://www.gpt-video.com/developers/changelog.md).

## Where the details are

- [Authentication](https://www.gpt-video.com/developers/authentication.md) shows how to create a key and which scopes it needs.
- The [quickstart](https://www.gpt-video.com/developers/quickstart.md) goes from a key to a downloaded clip.
- [Errors](https://www.gpt-video.com/developers/errors.md) gives every code and what to do next.
- [Pagination and idempotency](https://www.gpt-video.com/developers/pagination-and-idempotency.md) explains `limit`, `cursor` and the `Idempotency-Key` header.
- [Wait for long jobs](https://www.gpt-video.com/developers/jobs.md) shows how to follow a job and download an export.
- [Rate limits](https://www.gpt-video.com/developers/rate-limits.md) gives the limits per minute and per day.
- [Objects](https://www.gpt-video.com/developers/objects.md) describes the objects that many responses share.
- [API pricing](https://www.gpt-video.com/developers/pricing.md) covers credits, plans and the API bonus.

The page of each endpoint shows its parameters, a request in curl, TypeScript and Python, the response and the errors it can give.

## 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](https://www.gpt-video.com/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](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

| Code | Status | What to do |
| --- | --- | --- |
| [`VALIDATION_FAILED`](https://www.gpt-video.com/developers/errors.md#VALIDATION_FAILED) | 400 | Change the request, then send it again. |
| [`UNKNOWN_PARAMETER`](https://www.gpt-video.com/developers/errors.md#UNKNOWN_PARAMETER) | 400 | Change the request, then send it again. |
| [`IDEMPOTENCY_KEY_REQUIRED`](https://www.gpt-video.com/developers/errors.md#IDEMPOTENCY_KEY_REQUIRED) | 400 | Change the request, then send it again. |
| [`UNAUTHORIZED`](https://www.gpt-video.com/developers/errors.md#UNAUTHORIZED) | 401 | Stop and tell the user. |
| [`INSUFFICIENT_CREDITS`](https://www.gpt-video.com/developers/errors.md#INSUFFICIENT_CREDITS) | 402 | Stop and tell the user. |
| [`PLAN_REQUIRED`](https://www.gpt-video.com/developers/errors.md#PLAN_REQUIRED) | 402 | Stop and tell the user. |
| [`SCOPE_MISSING`](https://www.gpt-video.com/developers/errors.md#SCOPE_MISSING) | 403 | Stop and tell the user. |
| [`NOT_FOUND`](https://www.gpt-video.com/developers/errors.md#NOT_FOUND) | 404 | Change the request, then send it again. |
| [`METHOD_NOT_ALLOWED`](https://www.gpt-video.com/developers/errors.md#METHOD_NOT_ALLOWED) | 405 | Change the request, then send it again. |
| [`CONFLICT`](https://www.gpt-video.com/developers/errors.md#CONFLICT) | 409 | Read the resource again, then decide. Do not send the same request again. |
| [`NOT_READY`](https://www.gpt-video.com/developers/errors.md#NOT_READY) | 409 | Wait for Retry-After, then send the same request again. |
| [`IDEMPOTENCY_IN_PROGRESS`](https://www.gpt-video.com/developers/errors.md#IDEMPOTENCY_IN_PROGRESS) | 409 | Wait for Retry-After, then send the same request again. |
| [`PAYLOAD_TOO_LARGE`](https://www.gpt-video.com/developers/errors.md#PAYLOAD_TOO_LARGE) | 413 | Change the request, then send it again. |
| [`IDEMPOTENCY_KEY_REUSED`](https://www.gpt-video.com/developers/errors.md#IDEMPOTENCY_KEY_REUSED) | 422 | Change the request, then send it again. |
| [`SOURCE_MISSING`](https://www.gpt-video.com/developers/errors.md#SOURCE_MISSING) | 422 | Change the request, then send it again. |
| [`UNSUPPORTED_SOURCE_URL`](https://www.gpt-video.com/developers/errors.md#UNSUPPORTED_SOURCE_URL) | 422 | Change the request, then send it again. |
| [`RATE_LIMITED`](https://www.gpt-video.com/developers/errors.md#RATE_LIMITED) | 429 | Wait for Retry-After, then send the same request again. |
| [`DAILY_LIMIT_REACHED`](https://www.gpt-video.com/developers/errors.md#DAILY_LIMIT_REACHED) | 429 | Stop until the limit resets at 00:00 UTC. |
| [`INTERNAL`](https://www.gpt-video.com/developers/errors.md#INTERNAL) | 500 | Send the same request again with the same key, at most three times. |
| [`UPSTREAM_FAILED`](https://www.gpt-video.com/developers/errors.md#UPSTREAM_FAILED) | 502 | Send the same request again with the same key, at most three times. |
| [`UNAVAILABLE`](https://www.gpt-video.com/developers/errors.md#UNAVAILABLE) | 503 | Wait for Retry-After, then send the same request again. |

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](https://www.gpt-video.com/developers/errors.md) lists what each code means.

## IDs

| Prefix | What it is |
| --- | --- |
| `ast_` | A file in the account, such as an uploaded video |
| `trn_` | Transcript of an asset |
| `prj_` | Project |
| `cnd_` | Clip of a project |
| `cmp_` | Composition |
| `rnd_` | Export |
| `job_` | Job |
| `upl_` | Upload |
| `tml_` | Timeline of a Vibe Editing project |
| `seg_` | Segment of a timeline |
| `ovl_` | Text on a timeline |
| `brl_` | B-roll on a timeline |
| `cnv_` | Fake text story |
| `agm_` | Editor Assistant turn |
| `tc_` | Action of an Editor Assistant turn |
| `run_` | Tool run |

[IDs on the objects page](https://www.gpt-video.com/developers/objects.md#ids) 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`](https://www.gpt-video.com/developers/api/get-export.md) (`GET /v1/exports/{exportId}`). Save the file as soon as you download it.

## Upload

1. [`create_upload`](https://www.gpt-video.com/developers/api/create-upload.md) (`POST /v1/uploads`) opens an upload and says how many parts to send and how big each one is.
2. [`upload_part`](https://www.gpt-video.com/developers/api/upload-part.md) (`PUT /v1/uploads/{uploadId}/parts/{partNumber}`) sends each part as raw bytes, in any order.
3. [`complete_upload`](https://www.gpt-video.com/developers/api/complete-upload.md) (`POST /v1/uploads/{uploadId}/complete`) turns the parts into an asset that a project can use.

[Upload a video file](https://www.gpt-video.com/developers/guides/upload-a-video.md) has the whole loop in code.

## Using the API bonus

API bonus: 50 credits. No card needed.

- [`get_credits`](https://www.gpt-video.com/developers/api/get-credits.md) (`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.

| Name | As an MCP tool | As a REST operation, it takes |
| --- | --- | --- |
| `list_projects` (`GET /v1/projects`) | Takes limit, from 1 to 100, 20 by default. It answers in text and lists projects of every kind. | `limit`, `cursor` |
| `create_project` (`POST /v1/projects`) | Creates an empty project and returns an uploadUrl to upload the video in a browser. | `sourceAssetId`, `title`, `settings` |
| `get_project` (`GET /v1/projects/{projectId}`) | Takes the project id and answers in structured text for the model. | `projectId` |
| `list_clips` (`GET /v1/projects/{projectId}/clips`) | Takes limit, 10 by default. | `projectId`, `status`, `limit`, `cursor` |
| `get_job` (`GET /v1/jobs/{jobId}`) | Takes a job id (job_) or an export id (rnd_). | `jobId`, `wait` |

## 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`](https://www.gpt-video.com/developers/api/create-upload.md) `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`](https://www.gpt-video.com/developers/api/upload-part.md) `PUT /v1/uploads/{uploadId}/parts/{partNumber}`. Send each part as raw bytes.
3. [`complete_upload`](https://www.gpt-video.com/developers/api/complete-upload.md) `POST /v1/uploads/{uploadId}/complete`. Turn the upload into an asset. Keep `asset.id`.
4. [`create_project`](https://www.gpt-video.com/developers/api/create-project.md) `POST /v1/projects`. Create a project with that id as `sourceAssetId`. Keep `project.id`.
5. [`update_project`](https://www.gpt-video.com/developers/api/update-project.md) `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`](https://www.gpt-video.com/developers/api/estimate-analysis.md) `POST /v1/projects/{projectId}/analyze/estimate`. Check what the analysis will cost.
7. [`analyze_project`](https://www.gpt-video.com/developers/api/analyze-project.md) `POST /v1/projects/{projectId}/analyze`. Start the analysis with an `Idempotency-Key`. Keep `job.id`.
8. [`get_job`](https://www.gpt-video.com/developers/api/get-job.md) `GET /v1/jobs/{jobId}`. Read the job with `?wait=25` until `job.status` is final.
9. [`list_clips`](https://www.gpt-video.com/developers/api/list-clips.md) `GET /v1/projects/{projectId}/clips`. List the clips the analysis proposes.
10. [`accept_clip`](https://www.gpt-video.com/developers/api/accept-clip.md) `POST /v1/clips/{clipId}/accept`. Accept a clip. Keep `composition.id`.
11. [`create_export`](https://www.gpt-video.com/developers/api/create-export.md) `POST /v1/compositions/{compositionId}/exports`. Export the composition with an `Idempotency-Key`. Keep `export.id`.
12. [`get_export`](https://www.gpt-video.com/developers/api/get-export.md) `GET /v1/exports/{exportId}`. Read the export with `?wait=25` until it is done, then download `export.downloadUrl`.

## Endpoints

### Account and credits

- [`get_me`](https://www.gpt-video.com/developers/api/get-me.md) `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`](https://www.gpt-video.com/developers/api/get-credits.md) `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`](https://www.gpt-video.com/developers/api/list-ledger-entries.md) `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`](https://www.gpt-video.com/developers/api/create-upload.md) `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`](https://www.gpt-video.com/developers/api/upload-part.md) `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`](https://www.gpt-video.com/developers/api/get-upload.md) `GET /v1/uploads/{uploadId}`. Returns an open upload with the parts that arrived and the time it expires. Scope `clips:read`.
- [`complete_upload`](https://www.gpt-video.com/developers/api/complete-upload.md) `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`](https://www.gpt-video.com/developers/api/cancel-upload.md) `DELETE /v1/uploads/{uploadId}`. Cancels an open upload and deletes the parts sent so far. Scope `clips:write`.

### Videos and transcripts

- [`list_assets`](https://www.gpt-video.com/developers/api/list-assets.md) `GET /v1/assets`. Lists the videos you uploaded or imported, newest first, a page at a time. Scope `clips:read`.
- [`get_asset`](https://www.gpt-video.com/developers/api/get-asset.md) `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`](https://www.gpt-video.com/developers/api/get-transcript.md) `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`](https://www.gpt-video.com/developers/api/list-projects.md) `GET /v1/projects`. Returns the projects of the account, the most recently created first, one page at a time. Scope `clips:read`.
- [`create_project`](https://www.gpt-video.com/developers/api/create-project.md) `POST /v1/projects`. Creates an Auto Clip project on a video you uploaded, with the settings you choose. Scope `clips:write`.
- [`get_project`](https://www.gpt-video.com/developers/api/get-project.md) `GET /v1/projects/{projectId}`. Returns one project with its status, settings, missing settings and the analysis running on it. Scope `clips:read`.
- [`update_project`](https://www.gpt-video.com/developers/api/update-project.md) `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`](https://www.gpt-video.com/developers/api/analyze-project.md) `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`](https://www.gpt-video.com/developers/api/estimate-analysis.md) `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`](https://www.gpt-video.com/developers/api/list-clips.md) `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`](https://www.gpt-video.com/developers/api/get-clip.md) `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`](https://www.gpt-video.com/developers/api/accept-clip.md) `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`](https://www.gpt-video.com/developers/api/reject-clip.md) `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`](https://www.gpt-video.com/developers/api/restore-clip.md) `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`](https://www.gpt-video.com/developers/api/get-composition.md) `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`](https://www.gpt-video.com/developers/api/get-composition-captions.md) `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`](https://www.gpt-video.com/developers/api/list-compositions.md) `GET /v1/projects/{projectId}/compositions`. Lists the compositions of a project, the newest first, a page at a time. Scope `clips:read`.
- [`edit_composition`](https://www.gpt-video.com/developers/api/edit-composition.md) `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`](https://www.gpt-video.com/developers/api/replace-caption-words.md) `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`](https://www.gpt-video.com/developers/api/reframe-composition.md) `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`](https://www.gpt-video.com/developers/api/delete-composition.md) `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`](https://www.gpt-video.com/developers/api/create-export.md) `POST /v1/compositions/{compositionId}/exports`. Starts rendering a composition to an MP4 file and returns the export to follow. Scope `spend`.
- [`get_export`](https://www.gpt-video.com/developers/api/get-export.md) `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`](https://www.gpt-video.com/developers/api/list-exports.md) `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`](https://www.gpt-video.com/developers/api/create-split-screen-project.md) `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`](https://www.gpt-video.com/developers/api/update-split-screen-project.md) `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`](https://www.gpt-video.com/developers/api/build-split-screen-video.md) `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`](https://www.gpt-video.com/developers/api/create-streamer-project.md) `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`](https://www.gpt-video.com/developers/api/update-streamer-project.md) `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`](https://www.gpt-video.com/developers/api/build-streamer-video.md) `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`](https://www.gpt-video.com/developers/api/create-reddit-story-project.md) `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`](https://www.gpt-video.com/developers/api/update-reddit-story-project.md) `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`](https://www.gpt-video.com/developers/api/build-reddit-story-video.md) `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`](https://www.gpt-video.com/developers/api/create-fake-text-project.md) `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`](https://www.gpt-video.com/developers/api/update-fake-text-project.md) `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`](https://www.gpt-video.com/developers/api/get-fake-text-story.md) `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`](https://www.gpt-video.com/developers/api/update-fake-text-story.md) `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`](https://www.gpt-video.com/developers/api/generate-fake-text-story.md) `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`](https://www.gpt-video.com/developers/api/create-fake-text-voices.md) `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`](https://www.gpt-video.com/developers/api/create-voiceover.md) `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`](https://www.gpt-video.com/developers/api/separate-audio.md) `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`](https://www.gpt-video.com/developers/api/brainstorm-ideas.md) `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`](https://www.gpt-video.com/developers/api/get-tool-run.md) `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`](https://www.gpt-video.com/developers/api/list-tool-runs.md) `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`](https://www.gpt-video.com/developers/api/create-vibe-edit-project.md) `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`](https://www.gpt-video.com/developers/api/prepare-timeline.md) `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`](https://www.gpt-video.com/developers/api/get-timeline.md) `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`](https://www.gpt-video.com/developers/api/apply-timeline-operations.md) `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`](https://www.gpt-video.com/developers/api/add-timeline-clip.md) `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`](https://www.gpt-video.com/developers/api/list-timeline-revisions.md) `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`](https://www.gpt-video.com/developers/api/restore-timeline.md) `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`](https://www.gpt-video.com/developers/api/create-assistant-turn.md) `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`](https://www.gpt-video.com/developers/api/get-assistant-turn.md) `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`](https://www.gpt-video.com/developers/api/list-assistant-turns.md) `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`](https://www.gpt-video.com/developers/api/undo-assistant-action.md) `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`](https://www.gpt-video.com/developers/api/get-job.md) `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`](https://www.gpt-video.com/developers/api/get-setting-options.md) `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`](https://www.gpt-video.com/developers/api/list-voices.md) `GET /v1/reference/voices`. Lists the synthetic voices of a language that a voiceover can use. Scope `clips:read`.

[Every endpoint in one file](https://www.gpt-video.com/developers/api-full.md) has the page of each operation, one after the other.