Documentation Index
Fetch the complete documentation index at: https://docs.vatis.tech/llms.txt
Use this file to discover all available pages before exploring further.
Examples
Visit our GitHub samples repository for the complete list of examples on how to use the Vatis Streams API.
Prerequisites
- Vatis API key
- Linux shell
- cURL or Postman for making HTTP or WebSocket requests
- jq for parsing JSON responses
uuidgen for generating UUIDs- a testing audio/video file
Workflow
Export variables
export API_KEY=<your_api_key>
export STREAM_ID=$(uuidgen)
export FILE_PATH=<path_to_file>
Choose a stream configuration
The stream configuration defines what processing will be made on the input data (transcoding, transcription, diarization, audio intelligence, etc.). Pick one of the the predefined configurations:Export the configuration ID:export CONFIG_ID=<config_id>
Keep the stream configuration page opened in a separate tab for further references during this process
Upload the data
Use one of the available gateways for uploading the data.Set the streamConfigurationTemplateId=$CONFIG_ID, persist=true, and any other patches as query parameters and upload the binary data as the body of the request.The configuration-specific patches (parameters) can be found under the Parameters section of the configuration page.
When dealing with long parameter values (e.g. prompts) consider using the HTTP Gateway with form-data approach
Input data section of the configuration page.curl --request POST \
--url "https://http-gateway.vatis.tech/http-gateway/api/v1/upload?id=$STREAM_ID&streamConfigurationTemplateId=$CONFIG_ID&persist=true&language=en" \
--header "Authorization: Basic $API_KEY" \
--header 'Content-Type: application/octet-stream' \
--data-binary @"$FILE_PATH" | jq
To prevent any unexpected error, always include the Content-Type: application/octet-stream header
We can use dynamic webhooks to specify callback URLs at the request level that will be triggered when the state changes for the stream resource we’re creating. Generally, we’d want to know when the stream enters its COMPLETED or FAILED state.
To declare a webhook for this two events we should set the following query parameters:
webhook.stream.completed=http://my_domain/webhook-callbackwebhook.stream.failed=http://my_domain/webhook-callback
The URL value of the completed and failed webhooks can be the same, and the actual state can be parsed from the received body
The webhook URLs may need to be URL encoded depending on the requests library used
streamConfigurationTemplateId=$CONFIG_ID, persist=true, and any other patches as query parameters and upload the binary data as the body of the request.curl --request POST \
--url "https://http-gateway.vatis.tech/http-gateway/api/v1/upload?id=$STREAM_ID&streamConfigurationTemplateId=$CONFIG_ID&persist=true&language=en&webhook.stream.completed=http://my_domain/webhook-callback&webhook.stream.failed=http://my_domain/webhook-callback" \
--header "Authorization: Basic $API_KEY" \
--header 'Content-Type: application/octet-stream' \
--data-binary @"$FILE_PATH" | jq
In some scenarios, the patches (parameters) values are too long to be included in the URL. In this case, we can use the multipart/form-data content type to send the patches as form data.The request body will contain exactly two parts in this specific order:
- The patches as JSON encoded HTTPStreamConfigurationDto
- The binary data to be uploaded on the stream
Here’s an example of a stream configuration{
"patches": {
"languages": "ro" ①
},
"webhook": {
"http://my_domain/path": [ ②
"stream.completed", "stream.failed" ③
]
}
}
Parameters section of the configuration page② The webhook URL③ The events that will trigger the webhook. The complete list can be found hereThe complete request will look like this:curl --request POST \
--url "https://http-gateway.vatis.tech/http-gateway/api/v1/upload?id=$STREAM_ID&streamConfigurationTemplateId=$CONFIG_ID&persist=true" \
--header "Authorization: Basic $API_KEY" \
--header 'Content-Type: multipart/form-data' \
--form 'config={ "patches": {"language": "en"} };type=application/json' \
--form "file=@$FILE_PATH;type=application/octet-stream" | jq
- The first part has a limit of
1 MB
- If possible, include the part content type (
application/json, and application/octet-stream respectively)
- The parts name is not relevant
Wait for stream completion
Run the following command until the result is COMPLETED:curl --request GET \
--url "https://stream-service.vatis.tech/stream-service/api/v1/streams/$STREAM_ID" \
--header "Authorization: Basic $API_KEY" | jq '.state'
The configured webhook will be triggered with a POST request having the Webhook event payload containing the Stream state changed event.From the received payload we should extract the streamId and the state as shown below:{
//...
"payload": {
"streamId": "stream_id",
"state": "COMPLETED"
//...
}
}
FAILED, we should inspect the stream errors and retry the upload.Refer to the Webhook integration for the complete webhooks documentation. Export the final result
After the stream is completed, we can export the final result as JSON using the following command:curl --request GET \
--url "https://export-service.vatis.tech/export-service/api/v1/export/JSON?streams=$STREAM_ID" \
--header "Authorization: Basic $API_KEY" | jq
Export response section of the configuration. 
