> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Project Captions
> Read a project's caption lines, to correct them with Edit Project
## Overview
Answers the caption lines of a project as they are on its timeline now, with each word and its timing. Use it to find what to correct, then send the fixes to [Edit Project](/api-reference/project/edit) in `captionSegments`, by `index`.
* `index` counts from `0` across the whole video. A project made from a template has one caption layer per scene; their lines are numbered one after the other.
* `startMs` and `endMs` are milliseconds from the start of the video, for the line and for each word.
* `text` is the line as stored. The caption style may show it in upper case.
* `disabled`, `preset` and `alignment` are the captions' current switch, style and position.
* A project without captions answers `hasCaptions: false` and no segments. Captions cannot be added through the API.
A new caption style (`caption.preset`) re-cuts the lines to fit its box, so their number and indexes change. Read the captions again after changing the style.
```bash cURL theme={null}
curl -X GET "https://api.hooked.so/v1/project/cm4x9k2p10001ab12cd34ef56/captions" \
-H "x-api-key: your_api_key_here"
```
```javascript JavaScript theme={null}
const projectId = "cm4x9k2p10001ab12cd34ef56";
const response = await fetch(`https://api.hooked.so/v1/project/${projectId}/captions`, {
headers: { "x-api-key": process.env.HOOKED_API_KEY },
});
const { data } = await response.json();
for (const segment of data.segments) {
console.log(segment.index, `${segment.startMs}ms`, segment.text);
}
```
```python Python theme={null}
import os
import requests
project_id = "cm4x9k2p10001ab12cd34ef56"
response = requests.get(
f"https://api.hooked.so/v1/project/{project_id}/captions",
headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
)
for segment in response.json()["data"]["segments"]:
print(segment["index"], segment["startMs"], segment["text"])
```
```json 200 theme={null}
{
"success": true,
"message": "Captions fetched successfully",
"data": {
"projectId": "cm4x9k2p10001ab12cd34ef56",
"hasCaptions": true,
"disabled": false,
"preset": "classic",
"alignment": "bottom",
"segments": [
{
"index": 0,
"text": "Three habits that",
"startMs": 0,
"endMs": 1200,
"words": [
{ "word": "Three", "startMs": 0, "endMs": 400 },
{ "word": "habits", "startMs": 400, "endMs": 800 },
{ "word": "that", "startMs": 800, "endMs": 1200 }
]
},
{
"index": 1,
"text": "changed my mornings",
"startMs": 1200,
"endMs": 2600,
"words": [
{ "word": "changed", "startMs": 1200, "endMs": 1700 },
{ "word": "my", "startMs": 1700, "endMs": 1900 },
{ "word": "mornings", "startMs": 1900, "endMs": 2600 }
]
}
]
}
}
```
```json 404 theme={null}
{
"success": false,
"message": "Project not found"
}
```
## Errors
| Status | When |
| - | - |
| 401 | Missing or invalid API key (`code: "not_authenticated"`) |
| 403 | The team does not have the Hooked app product (`code: "entitlement_required"`) |
| 404 | No such project. Another team's project, or an id that is not one, answers the same `Project not found` |
| 500 | `Internal server error`. Retry |
## OpenAPI
````yaml GET /v1/project/{projectId}/captions
openapi: 3.0.0
info:
title: Hooked API
version: 1.0.0
description: AI Video Generation API
servers:
- url: https://api.hooked.so
security:
- ApiKeyAuth: []
tags:
- name: Videos
description: Create projects, follow them and render videos
- name: Account Analysis
description: Analyze TikTok and YouTube accounts
- name: Channels
description: Connected social accounts you publish to
- name: Publish
description: Schedule videos to your connected accounts
- name: Images
description: 'Image editing: background removal and expansion'
- name: Media
description: 'Your media library: list, import from a URL, upload a file'
- name: Avatars
description: Your team's own avatars (Actors) and their Hook + Demo reactions
paths:
/v1/project/{projectId}/captions:
get:
tags:
- Videos
summary: Get Project Captions
description: >-
The caption lines of a project, numbered as [Edit
Project](/api-reference/project/edit) takes them in `captionSegments`,
with each word and its timing. Read them before correcting a line: a new
caption style re-cuts the lines, so the numbers change after a
`caption.preset` edit. A project without captions answers `hasCaptions:
false` and no segments.
operationId: getProjectCaptions
parameters:
- name: projectId
in: path
required: true
schema:
type: string
description: >-
The `projectId` a create endpoint answered, or one from GET
/v1/project/list.
example: cm4x9k2p10001ab12cd34ef56
responses:
'200':
description: The project's captions
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: object
required:
- projectId
- hasCaptions
- disabled
- preset
- alignment
- segments
properties:
projectId:
type: string
hasCaptions:
type: boolean
description: >-
Whether the project has captions at all. Captions
cannot be added to a project that has none.
disabled:
type: boolean
description: >-
`true` when the captions are switched off (they stay
in the project and render again once switched on).
preset:
type: string
nullable: true
description: >-
The caption style (an id of GET
/v1/catalog/caption-presets), or `null` when unknown.
alignment:
type: string
nullable: true
enum:
- top
- middle
- bottom
description: 'Where the captions sit: `top`, `middle` or `bottom`.'
segments:
type: array
items:
type: object
required:
- index
- text
- startMs
- endMs
- words
properties:
index:
type: integer
description: >-
The number to send in `captionSegments[].index`.
Counts from 0 across the whole video.
text:
type: string
description: >-
The line as it shows on screen (before the
style's upper/lower case).
startMs:
type: integer
description: >-
When the line appears, in milliseconds from the
start of the video.
endMs:
type: integer
description: >-
When the line goes away, in milliseconds from
the start of the video.
words:
type: array
description: >-
The line's words with their times (milliseconds
from the start of the video); each word is
highlighted while it plays.
items:
type: object
required:
- word
- startMs
- endMs
properties:
word:
type: string
startMs:
type: integer
endMs:
type: integer
example:
success: true
message: Captions fetched successfully
data:
projectId: cm4x9k2p10001ab12cd34ef56
hasCaptions: true
disabled: false
preset: classic
alignment: bottom
segments:
- index: 0
text: Three habits that
startMs: 0
endMs: 1200
words:
- word: Three
startMs: 0
endMs: 400
- word: habits
startMs: 400
endMs: 800
- word: that
startMs: 800
endMs: 1200
- index: 1
text: changed my mornings
startMs: 1200
endMs: 2600
words:
- word: changed
startMs: 1200
endMs: 1700
- word: my
startMs: 1700
endMs: 1900
- word: mornings
startMs: 1900
endMs: 2600
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/EntitlementRequired'
'404':
description: >-
Not found. Another team's project, or an id that is not one, answers
the same way as a missing one.
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound404'
example:
success: false
message: Project not found
'429':
$ref: '#/components/responses/RateLimited429'
'500':
$ref: '#/components/responses/InternalError'
security:
- ApiKeyAuth: []
components:
responses:
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
EntitlementRequired:
description: The team does not have the product this endpoint needs
content:
application/json:
schema:
$ref: '#/components/schemas/EntitlementRequired403'
RateLimited429:
description: >-
Your team is over a rate limit: 30 POST requests per minute, 120 other
requests per minute, or 3 downloads of your URLs running at once.
Nothing ran and nothing was charged: wait `Retry-After` seconds and send
the request again. See [Rate
limits](/guides/error-handling#rate-limits-429).
headers:
Retry-After:
description: Seconds to wait before sending again.
schema:
type: integer
X-RateLimit-Limit:
description: The limit of the bucket you hit (not sent for the download cap).
schema:
type: integer
X-RateLimit-Remaining:
description: 'Requests left in this window: 0 (not sent for the download cap).'
schema:
type: integer
X-RateLimit-Reset:
description: >-
When the window ends, in Unix seconds (not sent for the download
cap).
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- RATE_LIMITED
message:
type: string
retryAfterSeconds:
type: integer
required:
- success
- errorCode
- message
- retryAfterSeconds
example:
success: false
errorCode: RATE_LIMITED
message: >-
Rate limit exceeded: 30 POST requests per minute per team. Retry
after 12 s.
retryAfterSeconds: 12
InternalError:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
schemas:
NotFound404:
type: object
description: >-
Not found. Another team's resource answers the same way as a missing
one.
properties:
success:
type: boolean
enum:
- false
message:
type: string
required:
- success
- message
example:
success: false
message: Project not found
Error401:
type: object
description: Missing or invalid `x-api-key`.
properties:
code:
type: string
enum:
- not_authenticated
message:
type: string
example: Not authenticated
errorCode:
type: string
enum:
- NOT_AUTHENTICATED
details:
type: object
additionalProperties:
type: string
example:
code: not_authenticated
message: Not authenticated
errorCode: NOT_AUTHENTICATED
details:
x-api-key: Header not provided or API Key invalid
EntitlementRequired403:
type: object
description: >-
Valid key, but the team does not have the product this endpoint belongs
to.
properties:
code:
type: string
enum:
- entitlement_required
error:
type: string
enum:
- entitlement_required
message:
type: string
product:
type: string
example: app
required:
- code
- error
- message
- product
example:
code: entitlement_required
error: entitlement_required
message: This endpoint requires the "app" product.
product: app
Error500:
type: object
properties:
success:
type: boolean
enum:
- false
message:
type: string
error:
type: string
description: Present on some endpoints
example:
success: false
message: Internal server error
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.