Build a Reddit story video

About

Call it when the post is written; estimate_analysis (POST /v1/projects/{projectId}/analyze/estimate) gives the price first. The build reads the post with a synthetic voice, times the captions on it and puts them over the background. The answer is 202 with the job of the build: follow it with get_job (GET /v1/jobs/{jobId}), then export the composition named by get_project (GET /v1/projects/{projectId}) with create_export (POST /v1/compositions/{compositionId}/exports). A build makes the video again from the settings, replacing the changes made to the composition in the GPT-Video editor. Retrying with the same Idempotency-Key never pays twice; a new key is a new build, and it is charged again.

Example use

After the post is final, a script builds the video with its synthetic voice and captions, follows the job with get_job (GET /v1/jobs/{jobId}), and exports the composition named by get_project (GET /v1/projects/{projectId}).

Endpoint

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

• 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

Headers

Request

Build a Reddit story video.

# 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_b71ffef7c27c5ea1cc87/reddit-story/build" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY"

// 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_b71ffef7c27c5ea1cc87/reddit-story/build", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
    "Idempotency-Key": idempotencyKey,
  },
});
const data = await res.json();
console.log(data);

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_b71ffef7c27c5ea1cc87/reddit-story/build",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
)
data = r.json()
print(data)

{
  "method": "tools/call",
  "params": {
    "name": "build_reddit_story_video",
    "arguments": {
      "projectId": "prj_b71ffef7c27c5ea1cc87",
      "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

Response example

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

{
  "error": {
    "code": "CONFLICT",
    "message": "This project uses a voice that is not available through the API. Choose one with update_reddit_story_project.",
    "requestId": "req_a7d4b1e8c5f20963b7d4e1a8"
  }
}

{
  "error": {
    "code": "CONFLICT",
    "message": "This project is not a Reddit story project. Use the operations of its kind, or analyze_project for an Auto Clip project.",
    "requestId": "req_f4b1e8a5d2c907f63a0e7b4d"
  }
}

Errors

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

Cost

One credit per build, whatever the length of the story, charged when the build starts and not returned if it fails. Building again is charged again.

• Paid by the API bonus, it uses the same number of bonus credits.
• When the API bonus pays, 1 of its jobs runs at a time. The next one waits with status queued.
• See API pricing for who pays first.

Related operations

• estimate_analysis (POST /v1/projects/{projectId}/analyze/estimate) Estimate the credits of an analysis or a build
• update_reddit_story_project (PATCH /v1/projects/{projectId}/reddit-story) Update a Reddit story project
• get_job (GET /v1/jobs/{jobId}) Get a job
• create_export (POST /v1/compositions/{compositionId}/exports) Export a composition
• list_voices (GET /v1/reference/voices) List the voices
• create_reddit_story_project (POST /v1/projects/reddit-story) Create a Reddit story project

Questions

What happens if my build request times out and I send it again?

Send it again with the same Idempotency-Key: the retry never pays twice, and it answers what the first try paid and who paid it. A new key is a new build, and it is charged again.

What happens to the changes I made in the GPT-Video editor?

A build makes the video of the project again from its settings, so it replaces the changes made to its composition in the editor. Change the settings with the update operation of the project, then build.

Why is my project's voice refused?

The project was made in the GPT-Video app with a voice the API does not offer. Choose one of list_voices (GET /v1/reference/voices) with update_reddit_story_project (PATCH /v1/projects/{projectId}/reddit-story), then build again.

View as Markdown