Captions API

Auto-captioning and multi-language translation

Endpoints

Method	Path	Summary
GET	/captions	List caption jobs
POST	/captions	Create a caption job
GET	/captions/{jobId}	Get a caption job
DELETE	/captions/{jobId}	Delete a caption job
GET	/captions/{jobId}/download	Download captions

---

GET /captions {#get-captions}

{% api-endpoint method=“GET” path=“/captions” /%}

List caption jobs

Operation ID: listCaptions

Query Parameters

| Name | Type | Required | Description | | --------- | ---------- | ------------ | ------------- | -------- | ------------ | --- | ------------------------------------------------------------------- | | page | integer | No | Default: 1 | | perPage | integer | No | Default: 20 | | videoId | string | No | - | | status | "pending" | "processing" | "completed" | "failed" | "cancelled" | No | Values: pending, processing, completed, failed, cancelled |

Responses

200 OK

Paginated list of caption jobs

Field	Type	Required	Description
data	object[]	No	-
pagination	object	No	-

Code Examples

{% tabs %} {% tab label=“TypeScript” %}

import { WaveClient } from "@wave/sdk";
 
const client = new WaveClient({ apiKey: "your-api-key" });
 
const result = await client.captions.listCaptions({
  page: 1,
  perPage: 1,
  videoId: "abc-123",
  status: "example-value",
});
console.log(result);

{% /tab %} {% tab label=“Python” %}

from wave_sdk import WaveClient
 
client = WaveClient(api_key="your-api-key")
 
result = client.captions.list_captions(
    page=1,
    per_page=1,
    video_id="abc-123",
    status="example-value"
)
print(result)

{% /tab %} {% tab label=“cURL” %}

curl -X GET 'https://api.wave.online/captions?page=1&perPage=1&videoId=abc-123&status=example-value' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{% /tab %} {% /tabs %}

---

POST /captions {#post-captions}

{% api-endpoint method=“POST” path=“/captions” /%}

Create a caption job

Operation ID: createCaptionJob

Request Body

Content-Type: application/json | Required

Field	Type	Required	Description
videoId	string	Yes	-
sourceLanguage	string	No	Default: "en"
targetLanguages	string[]	No	-
style	string	No	Default: "default"
speakerLabels	boolean	No	Default: false

Responses

201 Created

Caption job created

Field	Type	Required	Description
id	string	No	-
videoId	string	No	-
sourceLanguage	string	No	-
targetLanguages	string[]	No	-
status	string	No	Values: pending, processing, completed, failed, cancelled
progress	integer	No	-
outputs	object	No	-
errorMessage	string	No	-
organizationId	string	No	-
createdAt	string (date-time)	No	-
updatedAt	string (date-time)	No	-

Code Examples

{% tabs %} {% tab label=“TypeScript” %}

import { WaveClient } from "@wave/sdk";
 
const client = new WaveClient({ apiKey: "your-api-key" });
 
const result = await client.captions.createCaptionJob({
  videoId: "abc-123",
  sourceLanguage: "en",
  targetLanguages: [],
  style: "default",
  speakerLabels: false,
});
console.log(result);

{% /tab %} {% tab label=“Python” %}

from wave_sdk import WaveClient
 
client = WaveClient(api_key="your-api-key")
 
result = client.captions.create_caption_job(
    video_id="abc-123",
    source_language="example-value",
    target_languages=[],
    style="example-value",
    speaker_labels=True
)
print(result)

{% /tab %} {% tab label=“cURL” %}

curl -X POST 'https://api.wave.online/captions' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "videoId": "abc-123",
  "sourceLanguage": "en",
  "targetLanguages": [],
  "style": "default",
  "speakerLabels": false
}'

{% /tab %} {% /tabs %}

---

GET /captions/{jobId} {#get-captions}

{% api-endpoint method=“GET” path=“/captions/{jobId}” /%}

Get a caption job

Operation ID: getCaptionJob

Path Parameters

Name	Type	Required	Description
jobId	string	Yes	-

Responses

200 OK

Caption job details

Field	Type	Required	Description
id	string	No	-
videoId	string	No	-
sourceLanguage	string	No	-
targetLanguages	string[]	No	-
status	string	No	Values: pending, processing, completed, failed, cancelled
progress	integer	No	-
outputs	object	No	-
errorMessage	string	No	-
organizationId	string	No	-
createdAt	string (date-time)	No	-
updatedAt	string (date-time)	No	-

Code Examples

{% tabs %} {% tab label=“TypeScript” %}

import { WaveClient } from "@wave/sdk";
 
const client = new WaveClient({ apiKey: "your-api-key" });
 
const result = await client.captions.getCaptionJob("abc-123");
console.log(result);

{% /tab %} {% tab label=“Python” %}

from wave_sdk import WaveClient
 
client = WaveClient(api_key="your-api-key")
 
result = client.captions.get_caption_job(
    job_id="abc-123"
)
print(result)

{% /tab %} {% tab label=“cURL” %}

curl -X GET 'https://api.wave.online/captions/abc-123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{% /tab %} {% /tabs %}

---

DELETE /captions/{jobId} {#delete-captions}

{% api-endpoint method=“DELETE” path=“/captions/{jobId}” /%}

Delete a caption job

Operation ID: deleteCaptionJob

Path Parameters

Name	Type	Required	Description
jobId	string	Yes	-

Responses

204 No Content

Caption job deleted

Code Examples

{% tabs %} {% tab label=“TypeScript” %}

import { WaveClient } from "@wave/sdk";
 
const client = new WaveClient({ apiKey: "your-api-key" });
 
const result = await client.captions.deleteCaptionJob("abc-123");
console.log(result);

{% /tab %} {% tab label=“Python” %}

from wave_sdk import WaveClient
 
client = WaveClient(api_key="your-api-key")
 
result = client.captions.delete_caption_job(
    job_id="abc-123"
)
print(result)

{% /tab %} {% tab label=“cURL” %}

curl -X DELETE 'https://api.wave.online/captions/abc-123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{% /tab %} {% /tabs %}

---

GET /captions/{jobId}/download {#get-captions-download}

{% api-endpoint method=“GET” path=“/captions/{jobId}/download” /%}

Download captions

Operation ID: downloadCaptions

Path Parameters

Name	Type	Required	Description
jobId	string	Yes	-

Query Parameters

| Name | Type | Required | Description | | ---------- | -------- | -------- | ----------- | ------- | --- | ----------------------------------------------------- | | language | string | Yes | - | | format | "srt" | "vtt" | "txt" | "json" | No | Default: "srt". Values: srt, vtt, txt, json |

Responses

200 OK

Caption download

Field	Type	Required	Description
url	string (uri)	No	-
content	string	No	-

Code Examples

{% tabs %} {% tab label=“TypeScript” %}

import { WaveClient } from "@wave/sdk";
 
const client = new WaveClient({ apiKey: "your-api-key" });
 
const result = await client.captions.downloadCaptions("abc-123", {
  language: "example-value",
  format: "example-value",
});
console.log(result);

{% /tab %} {% tab label=“Python” %}

from wave_sdk import WaveClient
 
client = WaveClient(api_key="your-api-key")
 
result = client.captions.download_captions(
    job_id="abc-123",
    language="example-value",
    format="example-value"
)
print(result)

{% /tab %} {% tab label=“cURL” %}

curl -X GET 'https://api.wave.online/captions/abc-123/download?language=example-value&format=example-value' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{% /tab %} {% /tabs %}