Media (Audio/Video)

Upload your file with the Signed Url or External URL

If you want to add a hosted media (you must have a valid URL) to your media library, do it here.

Parameters

Please must specify mediaType as audio or video

name: String required
description: string;
url: string required; // public URL or AWS signed URL
mediaType: 'audio'; // 'video'
userId: ""; // for enterprise users only (optional)
medicalId: "" // custom media Id or medical Id for your reference (optional)
createdAt: "2021-08-09T00:13:11.717Z" // must match the date format (optional)
tags: "comma separated strings",
folderId: "folder Id" // to save in the folder
fields: { id: string, value: string } = []; (Optional)

Webhook Callback URL:

  • If you created a webhook for media events and want to receive a callback to a specific URL for this text note, you can assign callbackUrl - string in a req.body.

  • Speak will consider the callbackUrl and will skip the callbackUrl created via Webhook API.

Fields:

You can pass the id and value in the Fields array to include related to your media files.

Upload Considerations:

  • Maximum duration limit of 3 hours for a media URL.

  • The URL needs to be accessible publicly. For Example - Google Drive, Dropbox are not supported.

  • Valid YouTube URL examples are: https://www.youtube.com/watch?v=pTJ-yvNWCUE.

  • Supported File Formats are:

  • Audio - mp3 (recommended), m4a, wav, ogg, webm, m4p

  • Video - mp4 (recommended), m4v, wmv, avi, mov, flv

post/media/upload

Request

  • Base URL: https://api.speakai.co/v1
  • URL: https://api.speakai.co/v1/media/upload
  • Auth: API key in header x-speakai-key and API key in header x-access-token

Request body

namestring required

The title you want the uploaded file to have in Speak. Required. Trimmed. No maximum length and no pattern.

descriptionstring

A short description stored alongside the file. Optional. Trimmed. An empty string is allowed. The schema declares a default of an empty string, but the validation middleware discards the schema defaults, so an omitted value simply stays unset.

urlstring required

The link Speak fetches the file from. YouTube, Google Drive, Amazon S3 and the social platforms the resolver supports (TikTok, Instagram, X, Facebook, Reddit, SoundCloud, Twitch, Dailymotion, Streamable, Snapchat, Pinterest, Tumblr, Bilibili, VK, OK.ru and Rutube) are all handled. Vimeo and Loom page links are not resolved here: import Vimeo through the connected Vimeo integration instead. Required. Plain string with no uri format check, so the server does not reject a malformed link at validation time.

mediaType'audio' | 'video' | 'text' | 'media' | 'csv' | 'all'

The kind of file you are uploading, and the field that decides how it is stored and what can be run on it later. Send it whenever you know which you want, including for a page link: asking for audio on a YouTube link imports the audio track only. Leave it out when you do not know, and the server works it out from better evidence than you have: it inspects the file for a direct URL, and for a page link the resolver returns the best track the platform offers, which can still be audio when no video rendition fits the size limit. Either way the stored type follows what was actually fetched. It has no default, so leaving it out is a real choice rather than a value invented on your behalf, and the only fallback is audio when nothing else can be determined. Do not send a value guessed from the file extension. A value you send is kept, which means it stops the server inspecting the file, and a video stored as audio can never be analysed as video afterwards. Lowercased before validation, so uppercase values such as VIDEO are accepted. 'all' is a filter value that leaked into this schema: it validates but is not a real upload type.

sourceLanguagestring

The language spoken in the file, given as a transcription language code such as en-US. Optional. Any string passes, because the validator substitutes rather than rejects. An unrecognized code becomes auto. The schema declares a default of 'en-US', but that default is discarded by the middleware, so if you omit it the server uses the source language on your account onboarding and falls back to auto. Defined.

callbackUrlstring

A URL you want Speak to call when the file finishes processing. Optional. Trimmed. An empty string is allowed. Stored on the media as webhookMetaData.callbackUrl. No uri format check.

tagsstring

Tags to attach to the file, as a single comma separated string. Optional. Declared as a union, the schema) and allows null and an empty string, so an array also passes validation. The controller only reads a string and splits it on commas, so an array is accepted and then ignored.

createdAtstring

The creation timestamp to store on the file instead of the time of upload. Optional. An empty string is allowed. Parsed with new Date, so send an ISO 8601 string.

isTranscriptionOnlyboolean

Not used by this endpoint. Nothing in the upload flow reads it. Optional. Declared with a default of false, but that default is discarded and the value is never destructured or read by the controller.

folderIdstring

The folder you want the file to land in. If no folder with that id exists on your account, the server puts the file in your first folder. Optional. An empty string is allowed.

fieldsobject[]

Custom field values to attach to the file. Each entry pairs the id of a field you created in Speak with the value you want stored. Optional. An unconstrained array, so validation does not check the item shape and does not cap the length. The controller expects objects with id and value, checks each id against your account fields, and silently drops the ones that do not match (checkForValidFields ends with.filter(Boolean)).

Response

OK

statusstring

Changes

No recorded changes to this operation across all 2 revisions of this API.