Build a streamer video

About

Call it when the project has its settings; estimate_analysis (POST /v1/projects/{projectId}/analyze/estimate) gives the price first. The answer is 202 with the job of the build: follow it with get_job (GET /v1/jobs/{jobId}). When reframe is face, the build also starts computing the framing on the speaker's face, and create_export (POST /v1/compositions/{compositionId}/exports) answers NOT_READY until it is done. 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. If a build of the project is already running, you get that job back and nothing is charged.

Example use

A script builds the vertical video of a streamer project once the headline is set. It follows the job with get_job (GET /v1/jobs/{jobId}) and calls create_export (POST /v1/compositions/{compositionId}/exports) only when face framing is ready.

Endpoint

POST https://api.gpt-video.com/v1/projects/{projectId}/streamer/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 streamer 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_b9eb66e5ba20c4464f36/streamer/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_b9eb66e5ba20c4464f36/streamer/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_b9eb66e5ba20c4464f36/streamer/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_streamer_video",
    "arguments": {
      "projectId": "prj_b9eb66e5ba20c4464f36",
      "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_7a1d4f0c9e2b56a83d1c",
    "kind": "build",
    "status": "queued",
    "progress": 0,
    "errorMessage": null,
    "projectId": "prj_b9eb66e5ba20c4464f36",
    "compositionId": null,
    "exportId": null,
    "assetId": null,
    "toolRunId": null,
    "turnId": null,
    "createdAt": "2026-09-01T11:10:00.000Z",
    "startedAt": null,
    "finishedAt": null
  },
  "creditsCharged": 2,
  "reused": false,
  "paidWith": "plan"
}

{
  "error": {
    "code": "SOURCE_MISSING",
    "message": "A video this project uses no longer exists or cannot be used through the API. Create a new project with videos you uploaded.",
    "hint": "A project's video cannot be changed through the API. Upload the video, then create a new project with its asset id as sourceAssetId.",
    "requestId": "req_6a3e0d8b2f5c41a97e0d4b15"
  }
}

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

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 started minute of the clip, 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_streamer_project (PATCH /v1/projects/{projectId}/streamer) Update a streamer project
• get_job (GET /v1/jobs/{jobId}) Get a job
• get_project (GET /v1/projects/{projectId}) Get a project
• create_export (POST /v1/compositions/{compositionId}/exports) Export a composition
• create_streamer_project (POST /v1/projects/streamer) Create a streamer 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 does create_export answer NOT_READY after the build?

The framing on the speaker's face is computed after the build. Wait the seconds in Retry-After and send the export again with the same Idempotency-Key.

View as Markdown