namespace riviera import async import common route extract_async (ExtractArgs, async.LaunchResultBase, Void) "Asynchronous content extraction from a single file. One route covers every Riviera extraction. Name the source file in `file_id_or_url`, and say what to extract in `extract_type`, whose variant carries that extraction's options: - `markdown`: a document, converted to markdown that preserves its structure. - `text`: the plain text of a document. - `ocr`: the text of an image or scanned PDF, plus hOCR with per-word coordinates. - `transcript`: the timestamped transcript of an audio or video file. - `keyframes`: one keyframe per scene change in a video. The accepted formats and size limits differ per extraction; see `ExtractType`. Formats the requested extraction does not support fail with `unsupported_format_error`, and files over its size limit fail with `limit_exceeded_error`. The result is not returned by this route. Poll `extract_async/check` with the returned async job ID until it reports `complete` or `failed`. A `complete` result is an `ExtractResult` whose variant matches the requested `extract_type`." attrs auth = "app, user" is_preview = true scope = "files.content.read" route extract_async/check (async.PollArg, ExtractAsyncCheckResult, async.PollError) "Returns the status or result of specified extract_async task." attrs auth = "app, user" is_preview = true scope = "files.content.read" route download_transform_output (DownloadTransformOutputArgs, DownloadTransformOutputResult, TransformApiV2Error) "Download the output of a completed `get_transform_async` job. Pass the `output_handle` from the job's `complete` result. The body is the produced file, and the `Dropbox-API-Result` header describes it. A handle can only be redeemed by the user who requested the transform, and only until its `expires_ts`; after that this route fails with `expired_handle_error`, and the transform has to be requested again. A handle that was never valid, or that belongs to another user, fails with `user_error`." attrs auth = "app, user" host = "content" is_preview = true scope = "files.content.read" style = "download" route get_transform_async (TransformArgs, async.LaunchResultBase, Void) "Asynchronous file transformation: produces a new file from an existing one. One route covers many conversions. Name the source file in `file_id_or_url`, say what you want back in `transform_type`, and supply that type's options message if it needs one: - `pdf`: documents and images, to PDF. - `html`: spreadsheets, to HTML, preserving the sheet layout. - `image`: images and single document pages, to JPEG or PNG. - `thumbnail`: any thumbnailable source, resized to a named size bucket. - `image_pdf`: documents, to a page image rendered by way of PDF. - `video_frame`: one still frame from a video, at a requested offset. The accepted input formats differ per transform -- they are not one shared list -- and each is the intersection of the source format with the pipeline that transform uses: - `pdf` and `image_pdf`: word-processing, presentation and spreadsheet documents (.doc, .docx, .ppt, .pptx, .xls, .xlsx, .odt, .odp, .ods, .rtf, .epub, .gdoc, .gslides, .hwp, .ai, .eps, .dwg among others). Images are not accepted. - `html`: spreadsheets only -- .xls, .xlsm, .xlsx, .ods, .gsheet. This is the complete list. Note that .csv and .txt are *not* accepted here. - `image`: the documents above, plus .pdf and .html, plus the iWork and design formats .pages, .key, .numbers, .sketch, .xd, .indd and .psd, plus .avif, .heic, .svg and camera RAW, plus fonts (.otf, .ttf), plus video. Formats a browser can already display (.bmp, .gif, .ico, .jpeg, .png, .tif, .tiff, .webp) are not accepted; use `thumbnail` for those. - `thumbnail`: everything `image` accepts, plus .bmp, .gif, .ico, .jpeg, .png, .tif, .tiff, .webp and JPEG 2000. - `video_frame`: .3g2, .3gp, .3gpp, .3gpp2, .asf, .avi, .dv, .flv, .m2t, .m2ts, .m4v, .mkv, .mov, .mp4, .mpeg, .mpg, .mts, .mxf, .ogv, .rm, .ts, .vob, .webm, .wmv. This is the complete list. These lists track Riviera's capability registry (`dropbox/riviera/supported_types/previews_supported_types.yaml`), which is generated and authoritative; treat it rather than this comment as the final word. Formats the requested transform does not support fail with `unsupported_format_error`. Options belonging to a different transform type than the one requested fail with `invalid_options_error`. The produced bytes are not returned by this route, and not by its `/check` poll either. Poll `get_transform_async/check` with the returned async job ID until it reports `complete` or `failed`; a `complete` result carries a `TransformOutput` whose `output_handle` `download_transform_output` exchanges for the bytes. Splitting retrieval out this way is what lets the route return outputs larger than an async result can carry." attrs auth = "app, user" is_preview = true scope = "files.content.read" route get_transform_async/check (async.PollArg, GetTransformAsyncCheckResult, async.PollError) "Returns the status or result of specified get_transform_async task." attrs auth = "app, user" is_preview = true scope = "files.content.read" union TimestampLevel "Granularity of the time offsets returned for each transcript segment." sentence "One segment per spoken sentence (recommended). This is the default when :field:`GetTranscriptArgs.timestamp_level` is omitted." word "One segment per word, useful for fine-grained alignment such as captioning or highlight-as-you-listen experiences." struct MediaDurationError limit Int32 = 0 "The maximum supported duration, in seconds, of the audio to transcribe." union ContentApiV2Error "Reason a transcript job failed. Returned in the :field:`GetTranscriptAsyncCheckResult.failed` variant. 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 "The audio to transcribe is longer than the supported maximum." no_audio_error "The file has no audio track, or no audio content could be detected in it." link_download_disabled_error ":field:`FileIdOrUrl.url` referenced a Dropbox shared link whose owner has disabled downloads." shared_link_password_protected ":field:`FileIdOrUrl.url` referenced a password-protected Dropbox shared link. Riviera cannot supply the password, so such links cannot be transcribed." limit_exceeded_error "A resource limit was exceeded while producing the result." 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 for a file the authenticated user has access to, e.g. \"id:a4ayc_80_OEAAAAAAAAAYa\"." url String = "" "Either a Dropbox shared link (www.dropbox.com) or an internet-accessible 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; requests made with app auth alone are rejected. Password-protected links and links with downloads disabled are rejected as well. - Other URLs are fetched by Dropbox's servers, so they must be reachable from the public internet -- not only from the calling application's network -- 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 :route:`get_transcript_async` route. Exactly one of :field:`FileIdOrUrl.file_id`, :field:`FileIdOrUrl.path`, or :field:`FileIdOrUrl.url` must be supplied via :field:`GetTranscriptArgs.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 :type:`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 fail with :field:`ContentApiV2Error.no_audio_error`." timestamp_level TimestampLevel = sentence "Granularity of the time offsets returned for each transcript segment. Defaults to :field:`TimestampLevel.sentence` when the field is omitted." 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 = "" "Hint for the spoken language of the source audio, as an ISO 639-1 code (e.g. \"en\", \"ja\"). When empty, the service auto-detects the language; supplying a hint improves accuracy and latency for short or ambiguous clips. Languages the service does not support fall back to auto-detection." example default file_id_or_url = default timestamp_level = sentence struct ApiTranscriptSegment "A contiguous span of transcribed speech. The span covered by a segment depends on the requested :type:`TimestampLevel`." text String = "" "The transcribed text of this segment." start_time Float64 = 0 "Offset of the start of this segment, in seconds from the beginning of the media." end_time Float64 = 0 "Offset of the end of this segment, in seconds from the beginning of the media." struct ApiStructuredTranscript "A transcript, split into segments." segments List(ApiTranscriptSegment)? "The segments of the transcript, in playback order." transcript_locale String = "" "The language of the transcript, as an ISO 639-1 code (e.g. \"en\"). This is the language detected in the audio, or the one supplied in :field:`GetTranscriptArgs.audio_language`." struct GetTranscriptResult structured_transcript ApiStructuredTranscript? "The transcript produced for the requested media asset." union GetTranscriptAsyncCheckResult "Status of a transcript job started by :route:`get_transcript_async`, as returned by :route:`get_transcript_async/check`." in_progress "The job has not finished yet. Poll again." complete GetTranscriptResult "The job finished successfully." failed ContentApiV2Error "The job finished unsuccessfully." 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. Files in other formats fail with :field:`ContentApiV2Error.user_error`. Size limits: the source file must be at most 10 GB and its audio track at most 1 hour in duration. Files exceeding either limit fail with :field:`ContentApiV2Error.user_error`. The transcript is not returned by this route. Poll :route:`get_transcript_async/check` with the returned async job ID until it reports :field:`GetTranscriptAsyncCheckResult.complete` or :field:`GetTranscriptAsyncCheckResult.failed`." 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 MarkdownExtractOptions "Options for `ExtractType.markdown`." enable_ocr Boolean = false "Run OCR on PDF documents, so that scanned pages contribute text. Processing is slower when enabled." embed_images Boolean = false "Embed images as base64 data URIs in the markdown. This can significantly increase the size of the result." example default enable_ocr = false embed_images = false struct TextExtractOptions "Options for `ExtractType.text`. There are none yet; the variant carries a message so that options can be added later without changing its shape." struct OcrExtractOptions "Options for `ExtractType.ocr`. There are none yet; the variant carries a message so that options can be added later without changing its shape." struct TranscriptExtractOptions "Options for `ExtractType.transcript`." timestamp_level TimestampLevel = sentence "Granularity of the time offsets returned for each transcript segment. Defaults to `sentence`." included_special_words String = "" "Comma-delimited list of non-lexical filler words to keep in the transcript, e.g. \"uh, ah, uhm\". By default these fillers are stripped. Unrecognized tokens are ignored." audio_language String = "" "Hint for the spoken language of the audio, as an ISO 639-1 code such as \"en\" or \"ja\". When empty, the service detects the language. A language the service does not support fails with `user_error`." example default timestamp_level = sentence struct KeyframesExtractOptions "Options for `ExtractType.keyframes`." scene_change_threshold Float64 = 0 "Sensitivity of scene-change detection. A keyframe is emitted whenever the frame-to-frame scene score crosses this threshold, so a LOWER value yields MORE keyframes. When omitted (0.0) the service uses 0.3, a good starting point for most videos. Values above 1.0 fail with `user_error`." include_images Boolean = false "When true, each keyframe carries its JPEG image, base64-encoded, in `ApiKeyframe.image_base64`. When false (the default), only timestamps and scene scores are returned, which keeps the result small." example default scene_change_threshold = 0.3 include_images = false union ExtractType "What to extract from the source file, with that extraction's options. Exactly one variant must be set. Every variant carries an options message, so always send the object form -- for example `{\".tag\": \"text\"}` -- rather than a bare tag string. Option fields may be omitted to take their defaults." markdown MarkdownExtractOptions "Convert a document to markdown, preserving structure such as headings, lists, and tables. Supported formats: .binder, .docx, .html, .paper, .papert, .pptx, .xlsx, .gsheet, .ods, .pdf. At most 50 MB." text TextExtractOptions "Extract the plain text of a document. Supported formats: .doc, .docx, .docm, .rtf, .ppt, .pptx, .pptm, .xls, .xlsx, .xlsm, .pdf, .paper, .papert, .binder, .gdoc, .gsheet, .gslides, .txt, .vtt. At most 50 MB." ocr OcrExtractOptions "Run OCR on an image or a scanned PDF, returning reading-ordered text plus hOCR with per-word coordinates. Supported formats: .bmp, .gif, .heic, .jpeg, .jpg, .png, .tif, .tiff, .webp, .pdf. A PDF that already has a text layer is not OCRed and yields an empty result; use `text` for it. External (non-Dropbox) URLs are not supported." transcript TranscriptExtractOptions "Transcribe the audio of an audio or video file into timestamped segments. Supported audio formats: .aac, .aif, .aiff, .flac, .m4a, .m4r, .mp3, .oga, .ogg, .wav, .wma; video formats as for `keyframes`. At most 10 GB, with at most 1 hour of audio. A file with no audio track fails with `no_audio_error`." keyframes KeyframesExtractOptions "Detect scene changes in a video and return one keyframe per scene. Supported 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. At most 10 GB." example default markdown = default example transcript transcript = default struct ExtractArgs "Arguments for the asynchronous `extract_async` route. Exactly one of `file_id`, `path`, or `url` must be supplied via `file_id_or_url` to identify the source file, and `extract_type` must say what to extract from it." file_id_or_url FileIdOrUrl? "Identifier of the source file. Callers must set exactly one of the `FileIdOrUrl` variants. The file must be in a format the requested `extract_type` supports; see `ExtractType` for the per-type lists." extract_type ExtractType "What to extract, and that extraction's options. Required." example default file_id_or_url = default extract_type = default example transcript file_id_or_url = default extract_type = transcript union ExtractResult "A completed extraction. The variant always matches the `ExtractType` that was requested." markdown GetMarkdownResult "The markdown the document was converted to. May be empty when the document has no extractable text." text GetTextResult "The plain text of the document. May be empty when no text is found." ocr GetOcrResult "The OCR text and hOCR. Both may be empty when no text is detected." transcript GetTranscriptResult "The transcript. Its segments are empty when no speech is detected." keyframes GetKeyframesResult "The keyframes. Empty when no scene changes are detected." union ExtractApiV2Error "Reason an extraction job failed. Returned in the `failed` variant of `ExtractAsyncCheckResult`. 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), for example an out-of-range option. The string is a human-readable message; retrying the same request will not help." unsupported_format_error "The source file is not in a format the requested `extract_type` supports." link_download_disabled_error "`FileIdOrUrl.url` referenced a Dropbox shared link whose owner has disabled downloads." shared_link_password_protected "`FileIdOrUrl.url` referenced a password-protected Dropbox shared link. Riviera cannot supply the password, so such links cannot be read." limit_exceeded_error "A resource limit was exceeded: the source file is larger than the requested `extract_type` accepts, or the result would be too large to return. For `keyframes`, raise `scene_change_threshold` or turn off `include_images`; for `markdown`, turn off `embed_images`." conversion_failure_error "The source file was readable but could not be processed, for example because it is corrupt." 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." no_audio_error "`transcript` only: the source file has no audio track." union ExtractAsyncCheckResult "Status of an extraction job started by `extract_async`, as returned by `extract_async/check`." in_progress "The job has not finished yet. Poll again." complete ExtractResult "The job finished successfully." failed ExtractApiV2Error "The job finished unsuccessfully." struct GetKeyframesArgs "Arguments for the asynchronous `get_keyframes_async` route. Exactly one of `file_id`, `path`, or `url` must be supplied via `file_id_or_url` to identify the video whose scene-change keyframes should be extracted." file_id_or_url FileIdOrUrl? "Identifier of the video file to extract keyframes from. Callers must set exactly one of the `FileIdOrUrl` variants. Keyframe extraction is supported for video files only; see the route description for the supported formats. Requests against unsupported formats return `unsupported_format_error`." scene_change_threshold Float64 = 0 "Sensitivity of scene-change detection. A keyframe is emitted whenever the frame-to-frame scene score crosses this threshold, so a LOWER value yields MORE keyframes. Valid range is (0.0, 1.0]. When omitted (0.0) the service uses a default of 0.3, which is a good starting point for most videos." include_images Boolean = false "When true, each returned keyframe includes the JPEG image bytes, base64-encoded, in `ApiKeyframe.image_base64`. When false, the response contains only per-keyframe metadata (timestamp and scene score) and `image_base64` is left empty -- useful when you only need the scene boundaries and want a small response. NOTE: because the field defaults to false in proto3, callers who want images must set this explicitly to true." example default file_id_or_url = default scene_change_threshold = 0.3 include_images = true struct ApiKeyframe "A single extracted scene-change keyframe." timestamp Float64 = 0 "Presentation timestamp of the keyframe, in seconds from the start of the video." scene_score Float64 = 0 "Scene-change score that triggered this keyframe, in the range [0.0, 1.0]. Higher values indicate a more pronounced scene change relative to the preceding frame. The first keyframe of a video is always reported as 1.0: the start of a video is a scene boundary by definition, so that score is not a measured frame-to-frame comparison." image_base64 String = "" "The extracted frame as a base64-encoded JPEG image. Empty when the request set `include_images = false`." struct GetKeyframesResult frames List(ApiKeyframe)? "The extracted keyframes, ordered by `timestamp`. May be empty when no scene changes are detected in the source." union KeyframesExtractionApiV2Error "Reason a keyframe extraction job failed. Returned in the `failed` variant of `GetKeyframesAsyncCheckResult`. 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 "The source file is not in a format this route supports." link_download_disabled_error ":field:`FileIdOrUrl.url` referenced a Dropbox shared link whose owner has disabled downloads." shared_link_password_protected ":field:`FileIdOrUrl.url` referenced a password-protected Dropbox shared link. Riviera cannot supply the password, so such links cannot be processed." limit_exceeded_error "The request exceeded a service limit -- for example the source video is too large, or the extraction produced more keyframes / more total image data than the response can carry. Lower the resolution, raise `scene_change_threshold`, or set `include_images = false`." conversion_failure_error "The source file was readable but could not be processed, for example because it is corrupt." 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 GetKeyframesAsyncCheckResult "Result type for EventBus async check - must end in \"CheckResult\"" in_progress complete GetKeyframesResult failed KeyframesExtractionApiV2Error route get_keyframes_async (GetKeyframesArgs, async.LaunchResultBase, Void) "Asynchronous scene-change keyframe extraction for video files. Detects scene changes in the source video and returns one representative keyframe per detected scene, each tagged with its timestamp (seconds from the start of the video) and scene-change score. Set `include_images = true` to also receive each frame as a base64-encoded JPEG; when the field is omitted the response carries keyframe metadata only. 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`. Limits: the source file must be at most 10 GB. To keep responses within service limits the number of keyframes and the total image payload are bounded; requests that would exceed these limits return a `limit_exceeded_error` -- raise `scene_change_threshold` or set `include_images = false` to stay within bounds." attrs auth = "app, user" is_preview = true scope = "files.content.read" route get_keyframes_async/check (async.PollArg, GetKeyframesAsyncCheckResult, async.PollError) "Returns the status or result of specified get_keyframes_async task." attrs auth = "app, user" is_preview = true scope = "files.content.read" struct GetMarkdownArgs "Arguments for the asynchronous :route:`get_markdown_async` route. Exactly one of :field:`FileIdOrUrl.file_id`, :field:`FileIdOrUrl.path`, or :field:`FileIdOrUrl.url` must be supplied via :field:`GetMarkdownArgs.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 :type:`FileIdOrUrl` variants. The referenced file must be a document in a supported format (see the route description for the list); requests against unsupported formats fail with :field:`MarkdownConversionApiV2Error.user_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 markdown the source document was converted to." union MarkdownConversionApiV2Error "Reason a markdown conversion job failed. Returned in the :field:`GetMarkdownAsyncCheckResult.failed` variant. 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) -- for example an unsupported file format or a file over the size limit. The string is a human-readable message; retrying the same request will not help." unsupported_format_error "The source file is not in a format this route can convert." link_download_disabled_error ":field:`FileIdOrUrl.url` referenced a Dropbox shared link whose owner has disabled downloads." shared_link_password_protected ":field:`FileIdOrUrl.url` referenced a password-protected Dropbox shared link. Riviera cannot supply the password, so such links cannot be converted." limit_exceeded_error "A resource limit was exceeded while producing the result." conversion_failure_error "The source file was readable but could not be converted, for example because it is corrupt." 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 "Status of a markdown conversion job started by :route:`get_markdown_async`, as returned by :route:`get_markdown_async/check`." in_progress "The job has not finished yet. Poll again." complete GetMarkdownResult "The job finished successfully." failed MarkdownConversionApiV2Error "The job finished unsuccessfully." 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. Files in other formats fail with :field:`MarkdownConversionApiV2Error.user_error`. Size limit: the source file must be at most 50 MB. Larger files fail with :field:`MarkdownConversionApiV2Error.user_error`. The markdown is not returned by this route. Poll :route:`get_markdown_async/check` with the returned async job ID until it reports :field:`GetMarkdownAsyncCheckResult.complete` or :field:`GetMarkdownAsyncCheckResult.failed`." 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 :type:`ApiOfficeMetadata` result." office_filetype_unknown office_filetype_word office_filetype_powerpoint office_filetype_excel union MetadataType "Which metadata variant is populated in a :type:`GetMetadataResult`, derived from the file type." metadata_type_unknown "No metadata kind applies to the file, so no variant of :field:`GetMetadataResult.metadata` is populated. Riviera only produces metadata for the formats listed on :route:`get_metadata_async`; a request for any other file normally fails with :field:`MetadataExtractionApiV2Error.user_error` rather than completing with this value. An app that does receive it should treat the file as having no extractable metadata; retrying will not change the outcome." metadata_type_exif ":field:`metadata_union.exif` is populated." metadata_type_media ":field:`metadata_union.media` is populated." metadata_type_pdf ":field:`metadata_union.pdf` is populated." metadata_type_office ":field:`metadata_union.office` is populated." struct GetMetadataArgs "Arguments for the asynchronous :route:`get_metadata_async` route. Exactly one of :field:`FileIdOrUrl.file_id`, :field:`FileIdOrUrl.path`, or :field:`FileIdOrUrl.url` must be supplied via :field:`GetMetadataArgs.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 :type:`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 fail with :field:`MetadataExtractionApiV2Error.user_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 in decimal degrees (positive = north, negative = south)." longitude Float32 = 0 "Longitude in decimal degrees (positive = east, negative = west)." altitude String = "" "Altitude in meters, as reported by the source (string to preserve the original representation, which may include a reference direction)." timestamp String = "" "Time of the GPS fix, in the EXIF-provided format." datestamp String = "" "Date of the GPS fix, in the EXIF-provided format." struct ApiExifMetadata "Image EXIF metadata. Fields are populated on a best-effort basis and may be empty when absent from the source file." image_width UInt32 = 0 "Width of the image, in pixels." image_height UInt32 = 0 "Height of the image, in pixels." camera_make String = "" "Manufacturer of the device that captured the image, e.g. \"Apple\"." camera_model String = "" "Model of the device that captured the image, e.g. \"iPhone 15 Pro\"." lens_model String = "" "Model of the lens the image was captured with, when the source records it." date_time_original String = "" "Capture time in the EXIF-provided format (local time of the camera)." offset_time_original String = "" "Timezone offset for :field:`ApiExifMetadata.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 = "" "Exposure time the image was captured with, as a fractional-second string, e.g. \"1/250\"." aperture_value Float64 = 0 "Aperture the image was captured at, as reported by the EXIF aperture tag." iso_speed UInt32 = 0 "ISO sensitivity the image was captured at." focal_length String = "" "Focal length the image was captured at, including the unit, e.g. \"26.0 mm\"." megapixels Float64 = 0 "Total pixel count of the image, in megapixels." artist String = "" "Creator credited in the EXIF artist tag." copyright String = "" "Copyright notice from the EXIF copyright tag." gps_metadata ApiExifGpsMetadata? "Location tags from the image, when the source recorded a location." struct ApiMediaStream "A single audio or video stream within a media file." index UInt32 = 0 "Zero-based index of the stream within the container." codec_type String = "" "Kind of media the stream carries, e.g. \"audio\" or \"video\"." codec_name String = "" "Name of the codec the stream is encoded with, e.g. \"h264\" or \"aac\"." bitrate_bps UInt64 = 0 "Bitrate of this stream, in bits per second." duration_s Float64 = 0 "Duration of this stream, in seconds." width UInt32 = 0 "Width of the video frame, in pixels. Zero for audio streams." height UInt32 = 0 "Height of the video frame, in pixels. Zero for audio streams." frames_per_second Float64 = 0 "Frame rate of the stream, in frames per second. Zero for audio streams." rotation Int32 = 0 "Rotation to apply on playback, in degrees, as recorded in the stream metadata. Zero for audio streams and for video that needs no rotation." display_aspect_ratio String = "" "Aspect ratio the video should be displayed at, as a \"width:height\" string, e.g. \"16:9\". Empty for audio streams." channels UInt32 = 0 "Number of audio channels in the stream. Zero for video streams." channel_layout String = "" "Layout of the audio channels, e.g. \"stereo\". Empty for video streams." sample_rate_s UInt64 = 0 "Sample rate of the audio stream, in samples per second. Zero for video streams." language_iso_639 String = "" "ISO 639 language code for the stream, when present." struct ApiMediaMetadata "Audio/video container and per-stream metadata. Fields are populated on a best-effort basis and may be empty when absent from the source file." bitrate_bps UInt64 = 0 "Overall bitrate of the container, in bits per second." duration_s Float64 = 0 "Duration of the media, in seconds." creation_time String = "" "Container-level creation time, when present." streams List(ApiMediaStream)? "The audio and video streams the container holds, in container order." struct ApiPdfMetadata "PDF document metadata." pages UInt32 = 0 "Number of pages in the document." width UInt32 = 0 "Width of the first page, in PDF points." height UInt32 = 0 "Height of the first page, in PDF points." struct ApiOfficeMetadata "MS Office document metadata. Some fields apply only to specific document types (e.g. :field:`ApiOfficeMetadata.slides` for PowerPoint, :field:`ApiOfficeMetadata.words` and :field:`ApiOfficeMetadata.pages` for Word)." file_type OfficeFileType = office_filetype_unknown "Which kind of Office document this metadata was extracted from." creator String = "" "Author recorded in the document properties." company String = "" "Company recorded in the document properties." title String = "" "Title recorded in the document properties." subject String = "" "Subject recorded in the document properties." keywords String = "" "Keywords recorded in the document properties, in the document's own formatting (typically a single comma- or space-separated string)." description String = "" "Description recorded in the document properties." total_edit_time_minutes UInt32 = 0 "Total editing time recorded in the document properties, in minutes." pages UInt32 = 0 "Page count recorded in the document properties. Word documents only; zero for PowerPoint and Excel." words UInt32 = 0 "Word count recorded in the document properties. Word documents only; zero for PowerPoint and Excel." slides UInt32 = 0 "Slide count recorded in the document properties. PowerPoint documents only; zero for Word and Excel." revision_number String = "" "Revision number recorded in the document properties." struct GetMetadataResult metadata_type MetadataType = metadata_type_unknown "The kind of metadata that was extracted for the requested file. Callers should read the matching variant of :field:`GetMetadataResult.metadata`." metadata metadata_union? union "The extracted metadata. Exactly one variant is populated, corresponding to :field:`GetMetadataResult.metadata_type`." exif ApiExifMetadata "EXIF metadata, for image files." media ApiMediaMetadata "Container and per-stream metadata, for audio and video files." pdf ApiPdfMetadata "Document metadata, for PDFs." office ApiOfficeMetadata "Document metadata, for MS Office files." union MetadataExtractionApiV2Error "Reason a metadata extraction job failed. Returned in the :field:`GetMetadataAsyncCheckResult.failed` variant. 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) -- for example an unsupported file format or a file over the size limit for its metadata kind. The string is a human-readable message; retrying the same request will not help." unsupported_format_error "The source file is not in a format this route can extract metadata from." link_download_disabled_error ":field:`FileIdOrUrl.url` referenced a Dropbox shared link whose owner has disabled downloads." shared_link_password_protected ":field:`FileIdOrUrl.url` referenced a password-protected Dropbox shared link. Riviera cannot supply the password, so metadata cannot be extracted from such links." limit_exceeded_error "A resource limit was exceeded while producing the result." conversion_failure_error "The source file was readable but its metadata could not be extracted, for example because the file is corrupt." 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 "Status of a metadata extraction job started by :route:`get_metadata_async`, as returned by :route:`get_metadata_async/check`." in_progress "The job has not finished yet. Poll again." complete GetMetadataResult "The job finished successfully." failed MetadataExtractionApiV2Error "The job finished unsuccessfully." 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. Files in other formats fail with :field:`MetadataExtractionApiV2Error.user_error`. Size limits depend on the kind of metadata being extracted: at most 200 MB for image (EXIF) files, 100 GB for audio/video files, 500 MB for PDFs, and 288 MB for MS Office files. Files over the limit for their kind fail with :field:`MetadataExtractionApiV2Error.user_error`. The metadata is not returned by this route. Poll :route:`get_metadata_async/check` with the returned async job ID until it reports :field:`GetMetadataAsyncCheckResult.complete` or :field:`GetMetadataAsyncCheckResult.failed`." 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" struct GetOcrArgs "Arguments for the asynchronous `get_ocr_async` route. Exactly one of `file_id`, `path`, or `url` must be supplied via `file_id_or_url` to identify the image or PDF whose text should be extracted via OCR (optical character recognition)." file_id_or_url FileIdOrUrl? "Identifier of the file to run OCR on. Callers must set exactly one of the `FileIdOrUrl` variants. OCR is supported for image files and PDFs, including scanned / non-text PDFs; see the route description for the supported formats. Requests against unsupported formats return `unsupported_format_error`. NOTE: for the `url` variant, only Dropbox shared links (www.dropbox.com) are supported. External (non-Dropbox) URLs are not supported and return `unsupported_format_error`; import the file into Dropbox and reference it by `file_id` or `path` instead." example default file_id_or_url = default struct GetOcrResult text String = "" "The plain-text content extracted from the file via OCR. Words within a line are separated by a single space, lines are newline-separated in reading order, and for multi-page PDFs pages are separated by a blank line in page order. May be empty when no text is detected in the source." hocr String = "" "The same content as hOCR: HTML that carries the position of every recognized word. Each page is a `
` holding `

` elements with one `` per word, and each element carries `data-x`, `data-y`, `data-width`, and `data-height` attributes in pixels relative to the upright page (whose dimensions are on the `

`). Use this when you need word coordinates -- to highlight matches over a page image, for example; use `text` when you just need the words." union OcrExtractionApiV2Error "Reason an OCR extraction job failed. Returned in the `failed` variant of `GetOcrAsyncCheckResult`. 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 "The source file is not in a format this route supports." link_download_disabled_error ":field:`FileIdOrUrl.url` referenced a Dropbox shared link whose owner has disabled downloads." shared_link_password_protected ":field:`FileIdOrUrl.url` referenced a password-protected Dropbox shared link. Riviera cannot supply the password, so such links cannot be processed." limit_exceeded_error "A resource limit was exceeded while producing the result." conversion_failure_error "The source file was readable but could not be processed, for example because it is corrupt." 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 GetOcrAsyncCheckResult "Result type for EventBus async check - must end in \"CheckResult\"" in_progress complete GetOcrResult failed OcrExtractionApiV2Error route get_ocr_async (GetOcrArgs, async.LaunchResultBase, Void) "Asynchronous OCR (optical character recognition) text extraction for images and PDFs, including scanned / non-text PDFs. Supported formats: - Image formats: .bmp, .gif, .heic, .jpeg, .jpg, .png, .tif, .tiff, .webp. - PDF format: .pdf. Unsupported formats return an `unsupported_format_error`. For the `url` variant only Dropbox shared links are supported; external URLs return `unsupported_format_error`. Text-based PDFs already carry a text layer, so OCR is not run against them and the result is empty; use `get_text_async` to read the embedded text layer of such a PDF. The result carries the extracted words as plain text, plus the same content as hOCR with per-word coordinates." attrs auth = "app, user" is_preview = true scope = "files.content.read" route get_ocr_async/check (async.PollArg, GetOcrAsyncCheckResult, async.PollError) "Returns the status or result of specified get_ocr_async task." attrs auth = "app, user" is_preview = true scope = "files.content.read" struct GetTextArgs "Arguments for the asynchronous `get_text_async` route. Exactly one of `file_id`, `path`, or `url` must be supplied via `file_id_or_url` to identify the document whose plain-text content should be extracted." file_id_or_url FileIdOrUrl? "Identifier of the document to extract text from. Callers must set exactly one of the `FileIdOrUrl` variants. Text extraction is supported for common document formats (Word, PowerPoint, Excel, PDF, RTF, and Dropbox document types); see the route description for the supported formats. Requests against unsupported formats return `unsupported_format_error`. NOTE: for the `url` variant, only Dropbox shared links (www.dropbox.com) are supported. External (non-Dropbox) URLs are not supported and return `unsupported_format_error`; import the file into Dropbox and reference it by `file_id` or `path` instead." example default file_id_or_url = default struct GetTextResult text String = "" "The plain-text content extracted from the document. For multi-page documents the text is concatenated in document order. May be empty when no text is detected in the source." union TextExtractionApiV2Error "Reason a text extraction job failed. Returned in the `failed` variant of `GetTextAsyncCheckResult`. 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 "The source file is not in a format this route supports." link_download_disabled_error ":field:`FileIdOrUrl.url` referenced a Dropbox shared link whose owner has disabled downloads." shared_link_password_protected ":field:`FileIdOrUrl.url` referenced a password-protected Dropbox shared link. Riviera cannot supply the password, so such links cannot be processed." limit_exceeded_error "A resource limit was exceeded while producing the result." conversion_failure_error "The source file was readable but could not be processed, for example because it is corrupt." 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 GetTextAsyncCheckResult "Result type for EventBus async check - must end in \"CheckResult\"" in_progress complete GetTextResult failed TextExtractionApiV2Error route get_text_async (GetTextArgs, async.LaunchResultBase, Void) "Asynchronous plain-text extraction from documents. Supported formats include: - Word processing: .doc, .docx, .docm, .rtf. - Presentations: .ppt, .pptx, .pptm. - Spreadsheets: .xls, .xlsx, .xlsm. - PDF: .pdf. - Dropbox document types: .paper, .papert, .binder, .gdoc, .gsheet, .gslides. - Plain text / subtitles: .txt, .vtt. Unsupported formats return an `unsupported_format_error`. For the `url` variant only Dropbox shared links are supported; external URLs return `unsupported_format_error`." attrs auth = "app, user" is_preview = true scope = "files.content.read" route get_text_async/check (async.PollArg, GetTextAsyncCheckResult, async.PollError) "Returns the status or result of specified get_text_async task." attrs auth = "app, user" is_preview = true scope = "files.content.read" union TransformType "Which derived file to produce from the source file. Unlike the other Riviera content routes, which each expose one capability, `get_transform_async` is a single route over many conversions: the caller names the source file and the output it wants, and the service picks the conversion pipeline. Exactly one variant must be set; a request with none set fails with `invalid_options_error`." pdf "Convert the source document to PDF. Supported for word-processing, presentation, and spreadsheet documents; images are not accepted." html "Convert the source document to HTML. Supported for spreadsheets only, where HTML preserves the sheet layout that a PDF rendering flattens." image "Re-encode the source as a web-safe raster image (JPEG or PNG). This is the transform to use to normalize formats a browser cannot display directly -- HEIC, camera RAW, PSD, SVG -- and to render a single page of a document as an image. Formats a browser can already display, such as JPEG and PNG, are not accepted; use `thumbnail` to resize or re-encode those. Configured by `TransformArgs.image`." thumbnail "Produce a resized thumbnail of the source at one of the supported sizes. Configured by `TransformArgs.thumbnail`." image_pdf "Render the source as a page image by way of a PDF conversion, rather than by whichever image pipeline the source format would otherwise use. Prefer `image` unless you specifically need the PDF-rendered result; the two differ for formats that have a native image pipeline of their own (ebooks, for example). Configured by `TransformArgs.image`." video_frame "Extract a single frame from a video as a still image. Configured by `TransformArgs.video_frame`. This produces one frame at one requested offset. To get the set of scene-change keyframes across a whole video, use `get_keyframes_async`, which returns every detected frame with its timestamp and scene score." union ThumbnailSize "The size of the thumbnail to produce. These are the same named size buckets `files/get_thumbnail` supports, with the same meanings; arbitrary pixel dimensions are not accepted." w32h32 "32 by 32 px." w64h64 "64 by 64 px." w128h128 "128 by 128 px." w256h256 "256 by 256 px." w480h320 "480 by 320 px." w640h480 "640 by 480 px." w960h640 "960 by 640 px." w1024h768 "1024 by 768 px." w2048h1536 "2048 by 1536 px." union ThumbnailMode "How to resize and crop the source to reach the requested `ThumbnailSize`. These match `files/get_thumbnail`'s modes." strict "Scale down the image to fit within the given size." bestfit "Scale down the image to fit within the given size or its transpose." fitone_bestfit "Scale down the image to completely cover the given size or its transpose." original "Don't resize the image at all." union ThumbnailFormat "The encoding of the produced image. These match `files/get_thumbnail`'s formats: JPEG is the better choice for photographs, PNG for screenshots, line art, and anything with sharp text edges or transparency." jpeg "Lossy JPEG. The default, and the right choice for photographic sources." png "Lossless PNG, with alpha preserved." webp "WebP, which compresses better than either JPEG or PNG at comparable quality but is not readable by every consumer." struct ThumbnailOptions "Options for `TransformType.thumbnail`. Supplying this message with any other transform type fails with `invalid_options_error`." size ThumbnailSize = w64h64 "The size bucket to produce. Defaults to `w64h64` when omitted." mode ThumbnailMode = strict "How to fit the source into `size`. Defaults to `strict` when omitted." format ThumbnailFormat = jpeg "The output encoding. Defaults to `jpeg` when omitted." example default size = w64h64 mode = strict format = jpeg struct ImageOptions "Options for `TransformType.image` and `TransformType.image_pdf`. Supplying this message with any other transform type fails with `invalid_options_error`." page_number UInt32(min_value=1) = 1 "For multi-page sources (PDFs, presentations, documents), the 1-based page to render. Each request renders one page; to render a whole document, issue one request per page. Defaults to the first page when omitted." scale_percent UInt32(max_value=100, min_value=1) = 100 "Scale the rendered image to this percentage of its natural size. Must be in (0, 100] -- the pipeline does not upscale, so values above 100 are rejected with `invalid_options_error`. Defaults to 100 (no scaling) when omitted." example default page_number = 1 scale_percent = 100 struct VideoFrameOptions "Options for `TransformType.video_frame`. Supplying this message with any other transform type fails with `invalid_options_error`." offset_in_seconds Float64(min_value=0) = 0 "Offset into the video, in seconds, of the frame to extract. Should be within the video's duration. Defaults to 0 (the first frame) when omitted. Only the lower bound is enforced, because the upper bound is the source's duration, which is not known until the video is opened. An offset past the end is not rejected." scale_percent UInt32(max_value=100, min_value=1) = 100 "Scale the extracted frame to this percentage of the video's natural frame size. Must be in (0, 100]; the pipeline does not upscale. Defaults to 100 (no scaling) when omitted." example default offset_in_seconds = 12.5 scale_percent = 100 struct TransformArgs "Arguments for the asynchronous `get_transform_async` route. Exactly one of `file_id`, `path`, or `url` must be supplied via `file_id_or_url` to identify the source file, and exactly one variant of `transform_type` must be set to say what to produce from it. At most one options message may be set, and it must be the one belonging to the requested `transform_type`. Options that belong to a different transform type are rejected with `invalid_options_error` rather than ignored, so that a request whose parameters were misassembled fails visibly instead of quietly producing the wrong output." file_id_or_url FileIdOrUrl? "Identifier of the source file to transform. Callers must set exactly one of the `FileIdOrUrl` variants. The referenced file must be in a format the requested `transform_type` supports; see the route description for the per-transform format lists. Requests against unsupported formats fail with `unsupported_format_error`." transform_type TransformType "What to produce from the source file. Required." thumbnail ThumbnailOptions? "Options for `TransformType.thumbnail`." image ImageOptions? "Options for `TransformType.image` and `TransformType.image_pdf`." video_frame VideoFrameOptions? "Options for `TransformType.video_frame`." example default file_id_or_url = default transform_type = image image = default example thumbnail file_id_or_url = default transform_type = thumbnail thumbnail = default struct TransformOutput "A completed transform: a handle for retrieving the produced bytes, plus enough metadata to decide whether to retrieve them. The bytes themselves are deliberately not carried here. A completed async result is persisted, so it is bounded by a row-size limit well below the size of a typical converted document -- an inline payload would fail for exactly the large documents this route exists to convert. The transform therefore completes by caching its output and handing back `output_handle`, which `download_transform_output` exchanges for the bytes." output_handle String = "" "Opaque, single-purpose handle for the produced bytes. Pass it to `download_transform_output` to retrieve them. The handle is scoped to the account that created it and cannot be used to read anything other than the output of this transform. It is not a URL and carries no meaning for callers beyond being passed back verbatim." size UInt64 = 0 "Size of the produced output in bytes." format String = "" "Format of the produced output, as a short lowercase format name such as \"pdf\", \"html\", \"jpeg\", or \"png\". This reflects what was actually produced, which for some sources differs from what was requested." mime_type String = "" "MIME type corresponding to `format`, for callers that need a Content-Type to hand to a downstream consumer." expires_ts UInt64 = 0 "Unix timestamp, in seconds, after which `output_handle` is no longer accepted. Retrieve the bytes before this point; after it, `download_transform_output` reports `expired_handle_error` and the transform has to be requested again." union TransformApiV2Error "Reason a transform job failed. Returned in the `failed` variant of `GetTransformAsyncCheckResult`, and by `download_transform_output`. 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 "The source file is not in a format the requested `transform_type` can convert." link_download_disabled_error "`FileIdOrUrl.url` referenced a Dropbox shared link whose owner has disabled downloads." shared_link_password_protected "`FileIdOrUrl.url` referenced a password-protected Dropbox shared link. Riviera cannot supply the password, so such links cannot be transformed." limit_exceeded_error "A resource limit was exceeded while producing the result -- for example the source file is larger than the requested transform accepts." conversion_failure_error "The source file was readable but could not be converted, for example because it is corrupt." 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." invalid_options_error "`transform_type` was missing, or the supplied options did not match the requested transform type, or an option was out of range. The request is malformed; fix it rather than retrying it." expired_handle_error "The `output_handle` presented to `download_transform_output` has passed its `TransformOutput.expires_ts`. Request the transform again to get a fresh handle. Only `download_transform_output` produces this; a poll never does." union GetTransformAsyncCheckResult "Result type for EventBus async check - must end in \"CheckResult\"" in_progress "The job has not finished yet. Poll again." complete TransformOutput "The job finished successfully." failed TransformApiV2Error "The job finished unsuccessfully." struct DownloadTransformOutputArgs "Arguments for `download_transform_output`." output_handle String "The `output_handle` from a `complete` `get_transform_async/check` result." example default output_handle = "EXAMPLE_OUTPUT_HANDLE" struct DownloadTransformOutputResult "Describes the bytes in the response body. Returned in the `Dropbox-API-Result` header." size UInt64 = 0 "Size of the output in bytes." format String = "" "Format of the output, as a short lowercase format name such as \"pdf\", \"html\", \"jpeg\", or \"png\"." mime_type String = "" "MIME type corresponding to `format`."