Get the source transcript

GET

/videos/{videoId}/transcript

curl --request GET \
  --url https://api.braiv.co/v1/videos/vid_01JZ8M6A/transcript \
  --header 'Authorization: Bearer <token>'

• Braiv Public API

Returns processing state, or the complete segmented transcript and optional word-alignment artifact. Required scope: transcripts:read.

Authorizations

• bearerAuth
• apiKeyHeader

Parameters

Path Parameters

videoId

required

string

>= 1 characters

Braiv library video document ID.

Example

vid_01JZ8M6A

Responses

200

Transcript is ready.

Media type application/json

object

status

required

Source transcript lifecycle.

string

Allowed values: not_found processing ready failed

userVideoId

required

Parent library video ID.

string

language

Detected source language.

string

>= 2 characters <= 16 characters /^[A-Za-z]{2,3}(?:-[A-Za-z]{2,4})?$/

segments

Ordered transcript segments when ready.

Array<object>

object

start

required

Segment start in seconds.

number

end

required

Segment end in seconds; not earlier than start.

number

speaker

required

Speaker ID assigned to the segment.

string

text

required

Transcript text for this time range.

string

deleted

required

Whether the segment is excluded from active playback.

boolean

speakers

Speaker labels referenced by segments.

Array<object>

object

id

required

Speaker identifier referenced by segments.

string

label

required

Display label for the speaker.

string

wordAlignmentUrl

Temporary word-level alignment download URL.

string | null format: uri

wordAlignmentStoragePath

Canonical storage path for word alignment.

string | null

processingStatus

More detailed internal pipeline status when present.

string

Example

{
  "status": "ready",
  "userVideoId": "vid_01JZ8M6A",
  "language": "en",
  "segments": [
    {
      "start": 0.4,
      "end": 3.8,
      "speaker": "speaker_0",
      "text": "Welcome to our launch.",
      "deleted": false
    }
  ],
  "speakers": [
    {
      "id": "speaker_0",
      "label": "Ben"
    }
  ],
  "wordAlignmentUrl": "https://storage.googleapis.com/...",
  "wordAlignmentStoragePath": "user/videos/vid_01JZ8M6A/transcript/words.json"
}

202

Transcript is not ready; retry later.

Media type application/json

object

status

required

Source transcript lifecycle.

string

Allowed values: not_found processing ready failed

userVideoId

required

Parent library video ID.

string

language

Detected source language.

string

>= 2 characters <= 16 characters /^[A-Za-z]{2,3}(?:-[A-Za-z]{2,4})?$/

segments

Ordered transcript segments when ready.

Array<object>

object

start

required

Segment start in seconds.

number

end

required

Segment end in seconds; not earlier than start.

number

speaker

required

Speaker ID assigned to the segment.

string

text

required

Transcript text for this time range.

string

deleted

required

Whether the segment is excluded from active playback.

boolean

speakers

Speaker labels referenced by segments.

Array<object>

object

id

required

Speaker identifier referenced by segments.

string

label

required

Display label for the speaker.

string

wordAlignmentUrl

Temporary word-level alignment download URL.

string | null format: uri

wordAlignmentStoragePath

Canonical storage path for word alignment.

string | null

processingStatus

More detailed internal pipeline status when present.

string

Example

{
  "status": "processing",
  "userVideoId": "vid_01JZ8M6A",
  "processingStatus": "transcribing"
}

401

A supported authentication header is missing or contains an invalid Public API key.

Media type application/json

object

error

required

Structured public API error envelope.

object

code

required

Stable machine-readable error code.

string

Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL

message

required

Human-readable error summary.

string

details

required

Machine-readable operation-specific context; empty when unavailable.

object

key

additional properties

any

Examples

Authentication header missing

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Missing API key.",
    "details": {}
  }
}

API key invalid

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key",
    "details": {}
  }
}

403

Authentication succeeded, but the required scope, workspace role, or resource permission is missing.

Media type application/json

object

error

required

Structured public API error envelope.

object

code

required

Stable machine-readable error code.

string

Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL

message

required

Human-readable error summary.

string

details

required

Machine-readable operation-specific context; empty when unavailable.

object

key

additional properties

any

Examples

Example scope

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The API key lacks the required scope.",
    "details": {}
  }
}

404

The resource does not exist or is not accessible to the caller.

Media type application/json

object

error

required

Structured public API error envelope.

object

code

required

Stable machine-readable error code.

string

Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL

message

required

Human-readable error summary.

string

details

required

Machine-readable operation-specific context; empty when unavailable.

object

key

additional properties

any

Example

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found.",
    "details": {}
  }
}

422

Transcription reached a terminal failed state.

Media type application/json

object

status

required

Source transcript lifecycle.

string

Allowed values: not_found processing ready failed

userVideoId

required

Parent library video ID.

string

language

Detected source language.

string

>= 2 characters <= 16 characters /^[A-Za-z]{2,3}(?:-[A-Za-z]{2,4})?$/

segments

Ordered transcript segments when ready.

Array<object>

object

start

required

Segment start in seconds.

number

end

required

Segment end in seconds; not earlier than start.

number

speaker

required

Speaker ID assigned to the segment.

string

text

required

Transcript text for this time range.

string

deleted

required

Whether the segment is excluded from active playback.

boolean

speakers

Speaker labels referenced by segments.

Array<object>

object

id

required

Speaker identifier referenced by segments.

string

label

required

Display label for the speaker.

string

wordAlignmentUrl

Temporary word-level alignment download URL.

string | null format: uri

wordAlignmentStoragePath

Canonical storage path for word alignment.

string | null

processingStatus

More detailed internal pipeline status when present.

string

Example

{
  "status": "failed",
  "userVideoId": "vid_01JZ8M6A",
  "processingStatus": "failed"
}

429

The API key exceeded its allowed concurrency or request rate. Retry after in-flight work completes or the limit resets.

Media type application/json

object

error

required

Structured public API error envelope.

object

code

required

Stable machine-readable error code.

string

Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL

message

required

Human-readable error summary.

string

details

required

Machine-readable operation-specific context; empty when unavailable.

object

key

additional properties

any

Example

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API key concurrency limit reached",
    "details": {}
  }
}

500

An unexpected server error occurred.

Media type application/json

object

error

required

Structured public API error envelope.

object

code

required

Stable machine-readable error code.

string

Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL

message

required

Human-readable error summary.

string

details

required

Machine-readable operation-specific context; empty when unavailable.

object

key

additional properties

any

Example

{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred.",
    "details": {}
  }
}