Make the voices of a fake text story

create_fake_text_voicesPOST/v1/projects/{projectId}/story/voicesBeta

Starts making the voice of every line of the story that does not have it yet, and returns the job to follow.

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

Call it once the story is as you want it and voiceover is on. Only lines without their voice are voiced: new lines, lines whose words changed, and the lines of a side whose voice changed. The answer is 202 with the job: follow it with get_job (GET /v1/jobs/{jobId}), then export the video with create_export (POST /v1/compositions/{compositionId}/exports). If voices are already being made for the story, you get that job back and nothing is used (reused is true). A story whose lines all have their voice is refused before anything is used.

Example use

After the story is final, a script asks for the voice of every line that does not have one yet. It follows the job with get_job (GET /v1/jobs/{jobId}) and calls create_export (POST /v1/compositions/{compositionId}/exports) when it is done.

Endpoint

Code

POST https://api.gpt-video.com/v1/projects/{projectId}/story/voices

Scope spend.
Rate limit 10 requests a minute for each key and 20 for each account, shared by every spend call. See rate limits.
Idempotency-Key is required.
It starts work that runs on its own. The answer comes back before the work is done.

Parameters

Path

Name	Type	Required	Description
`projectId`	string	Required	The project id. It starts with prj_. Matches `^prj_[0-9a-f]{20}$`.

Headers

Name	Type	Required	Description
`Idempotency-Key`	string	Required	This operation spends, so the key is required. Create it once, before the request, and send the same key on every retry. From 1 to 255 visible characters, such as a UUID. See idempotency.

Request

Make the voices of the story.

curl

# Create the key once. Send this same key again if you retry this request.
IDEMPOTENCY_KEY=$(uuidgen)
curl -X POST "https://api.gpt-video.com/v1/projects/prj_ba8b07a88bfb14585459/story/voices" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"

TypeScript

// Create the key once. Send this same key again if you retry this request.
const idempotencyKey = crypto.randomUUID();
const res = await fetch("https://api.gpt-video.com/v1/projects/prj_ba8b07a88bfb14585459/story/voices", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
    "Idempotency-Key": idempotencyKey,
  },
});
const data = await res.json();
console.log(data);

Python

import os
import uuid

import requests

# Create the key once. Send this same key again if you retry this request.
idempotency_key = str(uuid.uuid4())
r = requests.post(
    "https://api.gpt-video.com/v1/projects/prj_ba8b07a88bfb14585459/story/voices",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
)
data = r.json()
print(data)

MCP (Full)

{
  "method": "tools/call",
  "params": {
    "name": "create_fake_text_voices",
    "arguments": {
      "projectId": "prj_ba8b07a88bfb14585459",
      "confirm": true,
      "idempotencyKey": "REPLACE-WITH-A-NEW-UUID-FOR-THIS-CALL"
    }
  }
}

Response

A successful call answers HTTP 202. Returns a Job object in job.

Fields to check

Name	Type	Description
`job.id`	string	The job id. It starts with job_.
`job.status`	string	queued and running are still working; done, failed and cancelled are final.
`reused`	boolean	true when making the voices was already running for this project and this is its job, paid by nobody again.
`paidWith`	string or null	Who paid for this request: plan is the credits or the daily allowance of the account's plan, api_bonus is the API bonus. null when this request paid nothing, because the same work was already running. A retry with the same Idempotency-Key says who paid the first time.

Response example

Location: https://api.gpt-video.com/v1/jobs/job_7d2c9a4e1f0b4386c5a2

HTTP 202

{
  "job": {
    "status": "queued",
    "progress": 0,
    "errorMessage": null,
    "projectId": "prj_ba8b07a88bfb14585459",
    "compositionId": null,
    "exportId": null,
    "assetId": null,
    "toolRunId": null,
    "turnId": null,
    "createdAt": "2026-09-01T11:10:00.000Z",
    "startedAt": null,
    "finishedAt": null,
    "id": "job_7d2c9a4e1f0b4386c5a2",
    "kind": "voices"
  },
  "reused": false,
  "paidWith": "plan"
}

All response fields

Name	Type	Required	Description
`job`	Job object	Required	Described in Job object.
`reused`	boolean	Required	true when making the voices was already running for this project and this is its job, paid by nobody again.
`paidWith`	string or null	Required	Who paid for this request: plan is the credits or the daily allowance of the account's plan, api_bonus is the API bonus. null when this request paid nothing, because the same work was already running. A retry with the same Idempotency-Key says who paid the first time. One of `plan`, `api_bonus`.

More examples