> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# Add audio / subtitle track

POST https://api.fastpix.com/v1/on-demand/{mediaId}/tracks
Content-Type: application/json

This endpoint allows you to add an audio or subtitle track to an existing media file using its `mediaId`. You need to provide the track `url` along with its `type` (audio or subtitle), `languageName` and `languageCode` in the request payload. You can optionally provide a `title` for the track.

#### How it works

1. Send a POST request to this endpoint, replacing `{mediaId}` with the media ID (`uploadId` or `id`).

2. Provide the necessary details in the request body.

3. Receive a response containing a unique track ID and the details of the newly added track.

#### Webhook events

1. After successfully adding a track, your system must receive the webhook event video.media.track.created.

2. Once the track is processed and ready, you must receive the webhook event video.media.track.ready.

3. Finally, an update event video.media.updated must notify your system about the media's updated status.

#### Example

Suppose you have a video uploaded to the FastPix platform, and you want to add an Italian audio track to it. By calling this API, you can attach an external audio file ([https://static.fastpix.com/music-1.mp3](https://static.fastpix.com/music-1.mp3)) to the media file. Similarly, if you need to add subtitles in different languages, you can specify type: `subtitle` with the corresponding subtitle `url`, `languageCode` and `languageName`.

Related guides: Add own subtitle tracks, Add own audio tracks

Reference: https://fastpix.com/docs/video-on-demand-api/manage-videos/add-media-track

## Authentication

- `Authorization` header (basic auth, required) — FastPix APIs are secured with Basic Authentication. Use your Access Token ID as the username and Secret Key as the password in the Authorization header of each API request. * Username: Access Token ID * Password: Secret Key Activate your FastPix account to generate your API credentials. See the guide here

## Request

### Path parameters

- `mediaId` (string, required) — The unique identifier assigned to the media when created. The value must be a valid UUID.

### Body (application/json)

This endpoint expects an object.

- `tracks` (AddTrackRequest, required) — Contains details about the track being added to the media file.

## Response

### 201

Media details updated successfully

- `success` (boolean, optional) — Demonstrates whether the request is successful or not.
- `data` (AddTrackResponse, optional) — Contains details about the track that was added or updated.

## Types

### AddTrackRequest

Contains details about the track being added to the media file.

- `url` (string, required, default: https://static.fastpix.com/music-1.mp3) — The direct URL of the track file. It must point to a valid audio or subtitle file.
- `type` (enum, required, default: audio) — Specifies the type of track being added. It can be either `audio` or `subtitle`.
  - Allowed values: `audio`, `subtitle`
- `languageCode` (string, required, default: it) — The BCP 47 language code representing the track’s language.
- `languageName` (string, required, default: Italian) — The full name of the language corresponding to the `languageCode`.
- `title` (string, optional) — Title of the track.

### AddTrackResponse

Contains details about the track that was added or updated.

- `id` (string, optional) — The unique identifier of the track.
- `type` (enum, optional) — Specifies the type of track (audio or subtitle).
  - Allowed values: `audio`, `subtitle`
- `url` (string, optional) — The direct URL of the track file.
- `languageCode` (string, optional) — The BCP 47 language code representing the track's language.
- `languageName` (string, optional) — The full name of the language corresponding to the `languageCode`.
- `title` (string, optional) — Title of the track.

## Examples

**Request**

```json
{
  "tracks": {
    "url": "https://static.fastpix.com/music-1.mp3",
    "type": "audio",
    "languageCode": "it-IT",
    "languageName": "Italian",
    "title": "Italian audio"
  }
}
```

**Response**

```json
{
  "success": true,
  "data": {
    "id": "ace60fc7-e876-4fc6-b9d9-c33fa242f84b",
    "type": "audio",
    "url": "https://static.fastpix.com/music-1.mp3",
    "languageCode": "it-IT",
    "languageName": "Italian",
    "title": "Italian audio"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6/tracks"

payload = { "tracks": {
        "url": "https://static.fastpix.com/music-1.mp3",
        "type": "audio",
        "languageCode": "it-IT",
        "languageName": "Italian",
        "title": "Italian audio"
    } }
headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, auth=("<username>", "<password>"))

print(response.json())
```

```javascript
const url = 'https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6/tracks';
const credentials = btoa("<username>:<password>");

const options = {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: '{"tracks":{"url":"https://static.fastpix.com/music-1.mp3","type":"audio","languageCode":"it-IT","languageName":"Italian","title":"Italian audio"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6/tracks"

	payload := strings.NewReader("{\n  \"tracks\": {\n    \"url\": \"https://static.fastpix.com/music-1.mp3\",\n    \"type\": \"audio\",\n    \"languageCode\": \"it-IT\",\n    \"languageName\": \"Italian\",\n    \"title\": \"Italian audio\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.SetBasicAuth("<username>", "<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6/tracks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request.basic_auth("<username>", "<password>")
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tracks\": {\n    \"url\": \"https://static.fastpix.com/music-1.mp3\",\n    \"type\": \"audio\",\n    \"languageCode\": \"it-IT\",\n    \"languageName\": \"Italian\",\n    \"title\": \"Italian audio\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6/tracks")
  .basicAuth("<username>", "<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tracks\": {\n    \"url\": \"https://static.fastpix.com/music-1.mp3\",\n    \"type\": \"audio\",\n    \"languageCode\": \"it-IT\",\n    \"languageName\": \"Italian\",\n    \"title\": \"Italian audio\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6/tracks', [
  'body' => '{
  "tracks": {
    "url": "https://static.fastpix.com/music-1.mp3",
    "type": "audio",
    "languageCode": "it-IT",
    "languageName": "Italian",
    "title": "Italian audio"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
    'auth' => ['<username>', '<password>'],
]);

echo $response->getBody();
```

```csharp
using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6/tracks");
client.Authenticator = new HttpBasicAuthenticator("<username>", "<password>");
var request = new RestRequest(Method.POST);

request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"tracks\": {\n    \"url\": \"https://static.fastpix.com/music-1.mp3\",\n    \"type\": \"audio\",\n    \"languageCode\": \"it-IT\",\n    \"languageName\": \"Italian\",\n    \"title\": \"Italian audio\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let credentials = Data("<username>:<password>".utf8).base64EncodedString()

let headers = [
  "Authorization": "Basic \(credentials)",
  "Content-Type": "application/json"
]
let parameters = ["tracks": [
    "url": "https://static.fastpix.com/music-1.mp3",
    "type": "audio",
    "languageCode": "it-IT",
    "languageName": "Italian",
    "title": "Italian audio"
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.fastpix.com/v1/on-demand/4fa85f64-5717-4562-b3fc-2c963f66afa6/tracks")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```