> ## 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. # Getting Started > Get started with the Vatis Streams API for pre-recorded content ## Examples Visit our [GitHub samples repository](https://github.com/Vatis-Tech/vatis-streams-samples) for the complete list of examples on how to use the Vatis Streams API. ## Prerequisites * [Vatis API key](/get-started/get-api-access) * Linux shell * [cURL](https://curl.se/) or [Postman](https://www.postman.com/) for making HTTP or WebSocket requests * [jq](https://jqlang.github.io/jq/) for parsing JSON responses * `uuidgen` for generating UUIDs * a testing audio/video file ## Workflow ```bash theme={null} export API_KEY= export STREAM_ID=$(uuidgen) export FILE_PATH= ``` 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: * [Pre-recorded transcription](/speech-to-text/pre-recorded/pre-recorded-transcription) * [Pre-recorded transcription w/ diarization](/speech-to-text/pre-recorded/speaker-diarization) Export the configuration ID: ```bash theme={null} export CONFIG_ID= ``` Keep the stream configuration page opened in a separate tab for further references during this process 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 The body will be sent as binary data on the request body. The actual body can be one of the options mentioned under the `Input data` section of the configuration page. ```bash theme={null} 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 [Endpoint reference](/api-reference/gateway/upload) We can use [dynamic webhooks](integration/webhooks#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-callback` * `webhook.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 We should also set the common `streamConfigurationTemplateId=$CONFIG_ID`, `persist=true`, and any other patches as query parameters and upload the binary data as the body of the request. ```bash theme={null} 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 ``` [Endpoint reference](/api-reference/gateway/upload) 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: 1. The patches as JSON encoded [HTTPStreamConfigurationDto](/api-reference/schemas/http-gateway/stream-configuration) 2. The binary data to be uploaded on the stream Here's an example of a stream configuration ```json theme={null} { "patches": { "languages": "ro" ① }, "webhook": { "http://my_domain/path": [ ② "stream.completed", "stream.failed" ③ ] } } ``` ① The configuration-specific patches (parameters) can be found under the `Parameters` section of the configuration page ② The webhook URL ③ The events that will trigger the webhook. The complete list can be found [here](/integration/webhooks#event-types) The complete request will look like this: ```bash theme={null} 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 ``` Considerations: * 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 [Endpoint reference](/api-reference/gateway/upload) Run the following command until the result is `COMPLETED`: ```bash theme={null} curl --request GET \ --url "https://stream-service.vatis.tech/stream-service/api/v1/streams/$STREAM_ID" \ --header "Authorization: Basic $API_KEY" | jq '.state' ``` [Endpoint reference](/api-reference/streams/stream-resource-impl/find-by-id) The configured webhook will be triggered with a `POST` request having the [Webhook event](/api-reference/schemas/webhook/webhook-event) payload containing the [Stream state changed event](/api-reference/schemas/webhook/event-payload/stream-state-event). From the received payload we should extract the `streamId` and the [state](/api-reference/schemas/stream/stream-state) as shown below: ```json theme={null} { //... "payload": { "streamId": "stream_id", "state": "COMPLETED" //... } } ``` If the stream state is `FAILED`, we should inspect the [stream errors](/infrastructure/streams/inspect-errors) and retry the upload. Refer to the [Webhook integration](/integration/webhooks) for the complete webhooks documentation. After the stream is completed, we can export the final result as JSON using the following command: ```bash theme={null} curl --request GET \ --url "https://export-service.vatis.tech/export-service/api/v1/export/JSON?streams=$STREAM_ID" \ --header "Authorization: Basic $API_KEY" | jq ``` Based on the stream configuration, the result will be the one mentioned under the `Export response` section of the configuration. [Endpoint reference](/api-reference/export/exports-a-stream-of-data-in-various-formats)