Captions

The Captions card transcribes audio or video into timed caption segments and attaches them to the cell as a caption layer for subtitle overlays in the final video.

Generate captions

POST /v1/vidsheet/{id}/cells/{cell_id}/generate?agent_id={agent_id}

Path parameters

Parameter	Type	Description
`id`	integer	The sheet ID.
`cell_id`	integer	The cell ID.

Request body

Field	Type	Required	Description
`generation_type`	string	Yes	`"captions"`.
`data.audio.value`	string (URI)	One of	Public URL of the audio to caption.
`data.video.value`	string (URI)	One of	Public URL of the video to caption (its audio track is extracted).
`data.trim`	object	No	`{ "start_seconds": number >= 0, "duration_seconds": number > 0 }` — caption only part of the source.

Pass exactly one of audio or video. No other fields are accepted.

Example

curl -X POST "https://api.gen.pro/v1/vidsheet/101/cells/3000/generate?agent_id=42" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "generation_type": "captions",
    "data": {
      "video": { "value": "https://cdn.gen.pro/outputs/final-abc123.mp4" },
      "trim": { "start_seconds": 0, "duration_seconds": 30 }
    }
  }'

You can also generate captions on a layer:

POST /v1/vidsheet/{id}/cells/{cell_id}/layers/{layer_id}/generate?agent_id={agent_id}

Response

Poll Check generation status until complete. The finished generation carries the transcript and timed segments in result (full_text, captions, audio_duration) and writes a caption layer onto the cell.

Errors

Status	Error code	Description
`422`	`validation_error`	No source, both `audio` and `video`, bad URI, or bad `trim`.
`404`	`not_found`	Sheet or cell not found.

Cell configuration

Field	Type	Description
`autoGenerate`	boolean	Auto-trigger generation when source audio/video changes.

Caption source is passed in the generation data parameter.