namespace riviera
import async
import common
union TimestampLevel
sentence
word
struct MediaDurationError
limit Int32 = 0
union ContentApiV2Error
"Reason a transcript job failed. Returned in the `failed` variant of
`GetTranscriptAsyncCheckResult`. This is a semantic error union: the HTTP
status of the poll request itself is unaffected (a poll that surfaces a
failed job is still a normal successful poll response). Callers should
branch on the variant."
server_error String = ""
"An unexpected, typically transient, server-side failure. The string is a
human-readable message; retrying with backoff may succeed."
user_error String = ""
"The request could not be processed as supplied (a problem with the
caller's input). The string is a human-readable message; retrying the
same request will not help."
media_duration_error MediaDurationError
no_audio_error
link_download_disabled_error
shared_link_password_protected
limit_exceeded_error
not_found_error
"The referenced file does not exist or is not accessible."
is_a_folder_error
"The target is a folder, not a file."
union FileIdOrUrl
file_id String = ""
"A Dropbox-issued file id (format: \"id:<id>\") for a file the
authenticated user has access to."
url String = ""
"Either a Dropbox shared link (www.dropbox.com) or an external HTTP or
HTTPS URL pointing to a supported file.
- Dropbox shared links are resolved internally using the caller's
authenticated identity and the link's visibility / download
settings. They therefore require an authenticated user context
(anonymous `url` requests against Dropbox links are rejected with an
`access_error`). Links protected by a password are rejected with
`shared_link_password_protected`; links with downloads disabled are
rejected with `link_download_disabled_error`.
- External URLs are fetched through the backend's egress proxy and must
point at a supported file extension."
path String = ""
"An absolute Dropbox path, e.g. \"/folder/example.pdf\"."
example default
path = "/folder/example.pdf"
struct GetTranscriptArgs
"Arguments for the asynchronous `get_transcript_async` route.
Exactly one of `file_id`, `path`, or `url` must be supplied via
`file_id_or_url` to identify the audio or video asset to transcribe."
file_id_or_url FileIdOrUrl?
"Identifier of the media asset to transcribe. Callers must set exactly one
of the `FileIdOrUrl` variants. The referenced asset must be an audio or
video file in a supported format (see the route description for the list);
requests against files with no audio track return a `no_audio_error`."
timestamp_level TimestampLevel = sentence
"Granularity of the time offsets returned for each transcript segment.
Defaults to `SENTENCE` when the field is omitted.
- SENTENCE: one segment per spoken sentence (recommended).
- WORD: one segment per word, useful for fine-grained alignment such
as captioning or highlight-as-you-listen experiences."
included_special_words String = ""
"Comma-delimited list of non-lexical filler words to preserve in the
transcript output, e.g. `\"uh, ah, uhm\"`. By default these fillers are
stripped. Unrecognized tokens are ignored. Leave empty to use the
default filtering behavior."
audio_language String = ""
"Optional ISO 639-1 two-letter language code hinting the spoken language of
the source audio (e.g. \"en\", \"ja\"). When empty, the service auto-detects
the language; supplying a hint improves accuracy and latency for short or
ambiguous clips. Unsupported languages fall back to auto-detection."
example default
file_id_or_url = default
timestamp_level = sentence
struct ApiTranscriptSegment
"Transcript segment for APIv2"
text String = ""
start_time Float64 = 0
end_time Float64 = 0
struct ApiStructuredTranscript
"Structured transcript for APIv2"
segments List(ApiTranscriptSegment)?
transcript_locale String = ""
struct GetTranscriptResult
structured_transcript ApiStructuredTranscript?
"The structured transcript produced for the requested media asset, with
per-segment text, start/end offsets (in seconds from the beginning of
the media), and the detected or caller-supplied locale."
union GetTranscriptAsyncCheckResult
"Result type for EventBus async check - must end in \"CheckResult\""
in_progress
complete GetTranscriptResult
failed ContentApiV2Error
route get_transcript_async (GetTranscriptArgs, async.LaunchResultBase, Void)
"Asynchronous transcript generation for audio and video files.
Supported audio formats: .aac, .aif, .aiff, .flac, .m4a, .m4r, .mp3, .oga,
.ogg, .wav, .wma. Supported video formats: .3gp, .3gpp, .3gpp2, .asf, .avi,
.dv, .flv, .m2t, .m2ts, .m4v, .mkv, .mov, .mp4, .mpeg, .mpg, .mts, .mxf,
.oggtheora, .ogv, .rm, .ts, .vob, .webm, .wmv. Unsupported formats return
an `unsupported_format_error`.
Size limits: the source file must be at most 10 GB and its audio track at
most 1 hour in duration. Files exceeding these limits are rejected."
attrs
auth = "app, user"
is_preview = true
scope = "files.content.read"
route get_transcript_async/check (async.PollArg, GetTranscriptAsyncCheckResult, async.PollError)
"Returns the status or result of specified get_transcript_async task."
attrs
auth = "app, user"
is_preview = true
scope = "files.content.read"
struct GetMarkdownArgs
"Arguments for the asynchronous `get_markdown_async` route.
Exactly one of `file_id`, `path`, or `url` must be supplied via
`file_id_or_url` to identify the document to convert to markdown."
file_id_or_url FileIdOrUrl?
"Identifier of the document to convert. Callers must set exactly one of the
`FileIdOrUrl` variants. The referenced file must be a document in a
supported format (see the route description for the list); requests
against unsupported formats return `unsupported_format_error`."
enable_ocr Boolean = false
"Enable OCR for PDF documents. Processing is slower when enabled."
embed_images Boolean = false
"When true, embed images as base64 data URIs in the markdown output.
This can significantly increase output size."
example default
file_id_or_url = default
enable_ocr = false
embed_images = false
struct GetMarkdownResult
markdown String = ""
"The converted markdown content"
union MarkdownConversionApiV2Error
"Reason a markdown conversion job failed. Returned in the `failed` variant of
`GetMarkdownAsyncCheckResult`. This is a semantic error union: the HTTP
status of the poll request itself is unaffected (a poll that surfaces a
failed job is still a normal successful poll response). Callers should
branch on the variant."
server_error String = ""
"An unexpected, typically transient, server-side failure. The string is a
human-readable message; retrying with backoff may succeed."
user_error String = ""
"The request could not be processed as supplied (a problem with the
caller's input). The string is a human-readable message; retrying the
same request will not help."
unsupported_format_error
link_download_disabled_error
shared_link_password_protected
limit_exceeded_error
conversion_failure_error
not_found_error
"The referenced file does not exist or is not accessible."
is_a_folder_error
"The target is a folder, not a file."
union GetMarkdownAsyncCheckResult
"Result type for EventBus async check"
in_progress
complete GetMarkdownResult
failed MarkdownConversionApiV2Error
route get_markdown_async (GetMarkdownArgs, async.LaunchResultBase, Void)
"Asynchronous document-to-markdown conversion for supported file formats.
Supported formats: .binder, .docx, .html, .paper, .papert, .pptx, .xlsx,
.gsheet, .ods, .pdf. Unsupported formats return an
`unsupported_format_error`.
Size limit: the source file must be at most 50 MB. Larger files are
rejected."
attrs
auth = "app, user"
is_preview = true
scope = "files.content.read"
route get_markdown_async/check (async.PollArg, GetMarkdownAsyncCheckResult, async.PollError)
"Returns the status or result of specified get_markdown_async task."
attrs
auth = "app, user"
is_preview = true
scope = "files.content.read"
union OfficeFileType
"The kind of MS Office document that produced an `ApiOfficeMetadata` result."
office_filetype_unknown
office_filetype_word
office_filetype_powerpoint
office_filetype_excel
union MetadataType
"Which metadata variant is populated in a `GetMetadataResult`, derived from
the file type."
metadata_type_unknown
metadata_type_exif
metadata_type_media
metadata_type_pdf
metadata_type_office
struct GetMetadataArgs
"Arguments for the asynchronous `get_metadata_async` route.
Exactly one of `file_id`, `path`, or `url` must be supplied via
`file_id_or_url` to identify the file whose metadata should be extracted."
file_id_or_url FileIdOrUrl?
"Identifier of the file to extract metadata from. Callers must set exactly
one of the `FileIdOrUrl` variants. The kind of metadata returned is
determined by the file type: image files return EXIF metadata, audio/video
files return media metadata, PDFs return PDF metadata, and MS Office
documents (docx, pptx, xlsx) return Office metadata. See the route
description for the supported formats. Requests against unsupported formats
return `unsupported_format_error`."
example default
file_id_or_url = default
struct ApiExifGpsMetadata
"GPS coordinates and related tags extracted from image EXIF data. Fields are
populated on a best-effort basis and may be empty when absent from the
source file."
latitude Float32 = 0
"Latitude / longitude in decimal degrees (positive = N/E, negative = S/W)."
longitude Float32 = 0
altitude String = ""
"Altitude in meters, as reported by the source (string to preserve the
original representation, which may include a reference direction)."
timestamp String = ""
"Timestamp / datestamp of the GPS fix, in the EXIF-provided format."
datestamp String = ""
struct ApiExifMetadata
"Image EXIF metadata. Mirrors the useful subset of the internal
`riviera.ExifMetadata` message. Fields are best-effort and may be empty."
image_width UInt32 = 0
image_height UInt32 = 0
camera_make String = ""
camera_model String = ""
lens_model String = ""
date_time_original String = ""
"Capture time in the EXIF-provided format (local time of the camera)."
offset_time_original String = ""
"Timezone offset for `date_time_original`, e.g. \"+09:00\"."
orientation UInt32 = 0
"EXIF orientation value (1-8). See the EXIF spec; 1 is the normal
upright orientation."
exposure_time String = ""
"fraction in string form, e.g. \"1/250\""
aperture_value Float64 = 0
iso_speed UInt32 = 0
focal_length String = ""
"e.g. \"26.0 mm\""
megapixels Float64 = 0
artist String = ""
copyright String = ""
gps_metadata ApiExifGpsMetadata?
struct ApiMediaStream
"A single audio or video stream within a media file."
index UInt32 = 0
codec_type String = ""
"\"audio\", \"video\", etc."
codec_name String = ""
bitrate_bps UInt64 = 0
duration_s Float64 = 0
width UInt32 = 0
"Video-specific fields (zero / empty for audio streams)."
height UInt32 = 0
frames_per_second Float64 = 0
rotation Int32 = 0
display_aspect_ratio String = ""
"e.g. \"16:9\""
channels UInt32 = 0
"Audio-specific fields (zero / empty for video streams)."
channel_layout String = ""
sample_rate_s UInt64 = 0
language_iso_639 String = ""
"ISO 639 language code for the stream, when present."
struct ApiMediaMetadata
"Audio/video container and per-stream metadata. Mirrors the useful subset of
the internal `riviera.MediaMetadata` message."
bitrate_bps UInt64 = 0
duration_s Float64 = 0
creation_time String = ""
"Container-level creation time, when present."
streams List(ApiMediaStream)?
struct ApiPdfMetadata
"PDF document metadata."
pages UInt32 = 0
width UInt32 = 0
"Width / height of the first page, in PDF points."
height UInt32 = 0
struct ApiOfficeMetadata
"MS Office document metadata. Mirrors the internal `riviera.OfficeMetadata`
message. Some fields apply only to specific document types (e.g. `slides`
for PowerPoint, `words`/`pages` for Word)."
file_type OfficeFileType = office_filetype_unknown
creator String = ""
company String = ""
title String = ""
subject String = ""
keywords String = ""
description String = ""
total_edit_time_minutes UInt32 = 0
pages UInt32 = 0
"Word only."
words UInt32 = 0
slides UInt32 = 0
"PowerPoint only."
revision_number String = ""
struct GetMetadataResult
metadata_type MetadataType = metadata_type_unknown
"The kind of metadata that was extracted for the requested file. Callers
should read the matching field of the `metadata` oneof."
metadata metadata_union?
union
"Exactly one variant is populated, corresponding to `metadata_type`."
exif ApiExifMetadata
media ApiMediaMetadata
pdf ApiPdfMetadata
office ApiOfficeMetadata
union MetadataExtractionApiV2Error
"Reason a metadata extraction job failed. Returned in the `failed` variant of
`GetMetadataAsyncCheckResult`. This is a semantic error union: the HTTP
status of the poll request itself is unaffected (a poll that surfaces a
failed job is still a normal successful poll response). Callers should
branch on the variant."
server_error String = ""
"An unexpected, typically transient, server-side failure. The string is a
human-readable message; retrying with backoff may succeed."
user_error String = ""
"The request could not be processed as supplied (a problem with the
caller's input). The string is a human-readable message; retrying the
same request will not help."
unsupported_format_error
link_download_disabled_error
shared_link_password_protected
limit_exceeded_error
conversion_failure_error
not_found_error
"The referenced file does not exist or is not accessible."
is_a_folder_error
"The target is a folder, not a file."
union GetMetadataAsyncCheckResult
"Result type for EventBus async check - must end in \"CheckResult\""
in_progress
complete GetMetadataResult
failed MetadataExtractionApiV2Error
route get_metadata_async (GetMetadataArgs, async.LaunchResultBase, Void)
"Asynchronous file metadata extraction for supported file formats. The kind
of metadata returned depends on the file type:
- Image (EXIF) formats: .3fr, .arw, .avif, .bmp, .cr2, .cr3, .crw, .dcr,
.dcs, .dng, .erf, .gif, .heic, .j2c, .j2k, .jp2, .jpc, .jpeg, .jpf,
.jpg, .jpg2, .jpm, .jpx, .kdc, .mef, .mos, .mrw, .nef, .nrw, .orf,
.pef, .png, .ppm, .r3d, .raf, .rw2, .rwl, .sr2, .tga, .tif, .tiff,
.wbmp, .web, .webp, .x3f.
- Audio/video (media) formats: .aac, .aif, .aiff, .flac, .m4a, .m4r,
.mp3, .oga, .ogg, .wav, .wma, .3gp, .3gpp, .3gpp2, .asf, .avi, .dv,
.flv, .m2t, .m2ts, .m4v, .mkv, .mov, .mp4, .mpeg, .mpg, .mts, .mxf,
.oggtheora, .ogv, .rm, .ts, .vob, .webm, .wmv.
- PDF format: .pdf.
- MS Office formats: .docx, .pptx, .xlsx.
Unsupported formats return an `unsupported_format_error`."
attrs
auth = "app, user"
is_preview = true
scope = "files.content.read"
route get_metadata_async/check (async.PollArg, GetMetadataAsyncCheckResult, async.PollError)
"Returns the status or result of specified get_metadata_async task."
attrs
auth = "app, user"
is_preview = true
scope = "files.content.read"