Create a streamer project

About

Call it after complete_upload (POST /v1/uploads/{uploadId}/complete), with the id of the clip. The clip and its language are chosen here and only here: to use another clip, create another project. The headline, the captions, the framing and the vocabulary can be changed later with update_streamer_project (PATCH /v1/projects/{projectId}/streamer). Nothing is built and no credits are used until you call build_streamer_video (POST /v1/projects/{projectId}/streamer/build). Send an Idempotency-Key: a retry without one creates a second project.

Example use

A streamer's editor uploads a stream highlight and creates a project with a headline, captions and reframe set to face, so the vertical video follows the speaker. It checks the price with estimate_analysis (POST /v1/projects/{projectId}/analyze/estimate) before the build.

Endpoint

POST https://api.gpt-video.com/v1/projects/streamer

• Scope clips:write.
• Rate limit 60 requests a minute for each key and 120 for each account, shared by every write call. See rate limits.
• Idempotency-Key is optional.

Parameters

Headers

Body

Send only the fields listed here. Any other field is refused with UNKNOWN_PARAMETER.

Request

Create a streamer project.

# 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/streamer" \
  -H "Authorization: Bearer $GPT_VIDEO_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceAssetId": "ast_8e21b0d94c6f4a17b358",
    "headline": "Watch the editor cut it",
    "language": "en",
    "captionStyle": "word-pop",
    "reframe": "face"
  }'

// 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/streamer", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GPT_VIDEO_API_KEY}`,
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "sourceAssetId": "ast_8e21b0d94c6f4a17b358",
    "headline": "Watch the editor cut it",
    "language": "en",
    "captionStyle": "word-pop",
    "reframe": "face"
  }),
});
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/streamer",
    headers={
        "Authorization": f"Bearer {os.environ['GPT_VIDEO_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
    json={
        "sourceAssetId": "ast_8e21b0d94c6f4a17b358",
        "headline": "Watch the editor cut it",
        "language": "en",
        "captionStyle": "word-pop",
        "reframe": "face"
    },
)
data = r.json()
print(data)

{
  "method": "tools/call",
  "params": {
    "name": "create_streamer_project",
    "arguments": {
      "sourceAssetId": "ast_8e21b0d94c6f4a17b358",
      "headline": "Watch the editor cut it",
      "language": "en",
      "captionStyle": "word-pop",
      "reframe": "face"
    }
  }
}

Response

A successful call answers HTTP 201. Returns a Project object in project.

Fields to check

Response example

{
  "project": {
    "id": "prj_0c7f3a95e1d24b68a4f2",
    "kind": "streamer",
    "title": "Streamer clip",
    "status": "draft",
    "sourceAssetId": "ast_8e21b0d94c6f4a17b358",
    "compositionId": null,
    "settings": null,
    "missingSettings": [],
    "errorMessage": null,
    "splitScreen": null,
    "streamer": {
      "sourceAssetId": "ast_8e21b0d94c6f4a17b358",
      "headline": "Watch the editor cut it",
      "language": "en",
      "captionStyle": "word-pop",
      "reframe": "face",
      "vocabulary": null
    },
    "redditStory": null,
    "fakeText": null,
    "vibeEdit": null,
    "createdAt": "2026-09-01T11:00:00.000Z",
    "updatedAt": "2026-09-01T11:00:00.000Z"
  }
}

{
  "sourceAssetId": "ast_0b1e5c9d3a7f40628e2d",
  "headline": "",
  "language": "en",
  "captionStyle": "word-pop",
  "reframe": "center"
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Asset ast_0b1e5c9d3a7f40628e2d not found",
    "hint": "Check the id. An id that belongs to another account is not found either.",
    "requestId": "req_0e5c8a2f7d1b43e96a0c5d28"
  }
}

{
  "sourceAssetId": "ast_e8a35ed674148f27b585",
  "headline": "",
  "language": "en",
  "captionStyle": "word-pop",
  "reframe": "center"
}

{
  "error": {
    "code": "CONFLICT",
    "message": "This asset is not a video. A streamer project needs a video clip.",
    "requestId": "req_7b2f9d4a1e6c05b38d7a2e40"
  }
}

Errors

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

Cost

No credits are used. The build is charged when you call build_streamer_video (POST /v1/projects/{projectId}/streamer/build).

Related operations

• update_streamer_project (PATCH /v1/projects/{projectId}/streamer) Update a streamer project
• build_streamer_video (POST /v1/projects/{projectId}/streamer/build) Build a streamer video
• estimate_analysis (POST /v1/projects/{projectId}/analyze/estimate) Estimate the credits of an analysis or a build
• complete_upload (POST /v1/uploads/{uploadId}/complete) Complete an upload
• get_setting_options (GET /v1/reference/setting-options) Get the setting options

Questions

Can I change the clip after creating the project?

No. The clip and its language are chosen when the project is created, because the price and the captions depend on them. To use another clip, create another project.

What does reframe do?

face makes the vertical video follow the face of the speaker, which is computed after the build; center keeps the middle of the frame. Change it with update_streamer_project (PATCH /v1/projects/{projectId}/streamer), then build again.

View as Markdown