Documentation
Clip Endpoints
Create a clip
POST
https://api.soundmadeseen.com/public/v1/uploads/upload_key/create-clip/
The Create a clip endpoint creates a clip from the file upload specified by "upload_key".
If the file upload that this clip is extracted from contains a transcription, the appropriate part of the file upload's transcription will be copied over to a new transcription which is associated with this clip.
This endpoint accepts the following path parameters:
- upload_key - the key or identifier of the upload to generate the clip from.
This endpoint requires the following body (form) parameters:
- start - a float value in seconds from the beginning of the file upload. Defines the start of the clip. Must be a non negative value.
- end - a float value in seconds from the beginning of the file upload. Defines the end of the clip. Must be a non negative value and greater than the start value.
This endpoint accepts the following optional body (form) parameters:
- name - if this field is specified, set the name of the clip. If it is not specified, the name of the clip will be automatically generated.
- transcribe - if there is not already a transcription for the original file upload, and this is set to true, then a new transcription will be generated.
- number_of_speakers - if transcribe is set to true, then the number of speakers in the clip can be set as a hint for the transcription engine. If this field is not set, the transcription engine will guess.
- language_code - if transcribe is set to true, and there is not a transcription for the original file upload, the language code of the new transcription can be set from the list of acceptable language codes.
Responses
If successful this endpoint will return a response with an HTTP status code of 201 and an output similar to the following:
{
"success": true,
"key": "Zk74kjXdFLekwWDdPZhDpr"
}
The key value from this response can be used to check the status of the clip using the Check Clip Status endpoint, documented below.
If the response is unsuccessful, the response will return an HTTP status code in the 400 range with error output similar to the following:
{
"success": false,
"error": "Start and end times are required"
}
Some code examples follow:
Code examples
import requests
# Replace these with your actual values
API_KEY = "MY_API_KEY"
UPLOAD_KEY = "<upload_key>" # Replace with the actual upload_key
URL = f"https://api.soundmadeseen.com/public/v1/uploads/{UPLOAD_KEY}/create-clip/"
# Parameters for the clip
params = {
"start": 10.5, # Start time in seconds
"end": 20.0, # End time in seconds
"name": "My New Clip" # Name of the clip
}
# Headers
headers = {
"Authorization": f"Api-Key {API_KEY}",
"Content-Type": "application/json"
}
# Make the POST request
response = requests.post(URL, json=params, headers=headers)
# Handle the response
if response.status_code == 200:
result = response.json()
if result.get("success"):
print("Clip created successfully!")
print(f"Clip Key: {result['key']}")
else:
print("Failed to create clip. Response:", result)
else:
print("Error:", response.status_code)
print("Response:", response.text)
const axios = require('axios');
// Replace these with your actual values
const API_KEY = "MY_API_KEY";
const UPLOAD_KEY = "<upload_key>"; // Replace with the actual upload key
const URL = `https://api.soundmadeseen.com/public/v1/uploads/${UPLOAD_KEY}/create-clip/`;
// Parameters for the clip
const params = {
start: 10.5, // Start time in seconds
end: 20.0, // End time in seconds
name: "My New Clip" // Name of the clip
};
// Headers
const headers = {
"Authorization": `Api-Key ${API_KEY}`,
"Content-Type": "application/json"
};
// Make the POST request
axios
.post(URL, params, { headers })
.then(response => {
if (response.status === 200 && response.data.success) {
console.log("Clip created successfully!");
console.log("Clip Key:", response.data.key);
} else {
console.error("Failed to create clip:", response.data);
}
})
.catch(error => {
if (error.response) {
console.error("Error response:", error.response.status, error.response.data);
} else {
console.error("Error:", error.message);
}
});
curl -X POST https://api.soundmadeseen.com/public/v1/uploads/<upload_key>/create-clip/ \
-H "Authorization: Api-Key MY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"start": 10.5,
"end": 20.0,
"name": "My New Clip"
}'
<?php
// Replace these with your actual values
$apiKey = "MY_API_KEY";
$uploadKey = "<upload_key>"; // Replace with the actual upload key
$url = "https://api.soundmadeseen.com/public/v1/uploads/$uploadKey/create-clip/";
// Parameters for the clip
$data = [
"start" => 10.5, // Start time in seconds
"end" => 20.0, // End time in seconds
"name" => "My New Clip" // Name of the clip
];
// Initialize cURL
$ch = curl_init();
// Set cURL options
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Api-Key $apiKey",
"Content-Type: application/json"
],
CURLOPT_POSTFIELDS => json_encode($data),
]);
// Execute the request
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// Check for errors
if (curl_errno($ch)) {
echo "cURL error: " . curl_error($ch);
} else {
if ($httpCode === 200) {
$result = json_decode($response, true);
if ($result["success"]) {
echo "Clip created successfully!\n";
echo "Clip Key: " . $result["key"] . "\n";
} else {
echo "Failed to create clip. Response: " . $response . "\n";
}
} else {
echo "Error: HTTP $httpCode\n";
echo "Response: " . $response . "\n";
}
}
// Close cURL session
curl_close($ch);
List Clips
GET
https://api.soundmadeseen.com/public/v1/clips/
This endpoint provides a listing of clips belonging to the current team.
This endpoint accepts the following querystring parameters:
- order - sets the field that determines the order results are returned. May accept the following values: 'created_date', 'name' or 'duration'. Defaults to 'created_date'
- dir - sets the direction that determines the order results are returned. May have the values 'asc' and 'desc'. Defaults to 'desc'.
- page - responses of this request are paginated and have a page size of 12. Setting this parameter will return the appropriate page. Defaults to 1.
Response
If successful, returns an HTTP status code of 200 with a paginated response similar to the following:
{
"count": 2,
"current": 1,
"total_pages": 1,
"page_size": 12,
"start_index": 1,
"end_index": 2,
"extra_params": {},
"results": [
{
"key": "Zk74kjXdFLekwWDdPZhDpr",
"audio_file_upload": "MFeBLAYGhUwEt6i3SriWKB",
"created_date": "2025-01-25T02:49:05.299742Z",
"name": "Demonstration clip",
"original_end": 115.5,
"original_start": 0,
"duration": 115.5
},
{
"key": "jDKXpnQ3zceYqqcmXtgeEm",
"audio_file_upload": "iwhESqoQdPVkxURbUvAUN5",
"created_date": "2025-01-24T22:38:33.552155Z",
"name": "Another Demonstration clip",
"original_end": 66.18660541572054,
"original_start": 0,
"duration": 66.18660541572054
}]
}
Some code examples follow:
Code examples
import requests
API_KEY = "MY_API_KEY" # Replace this with your actual API key
URL = "https://api.soundmadeseen.com/public/v1/clips/"
# Headers
headers = {
"Authorization": f"Api-Key {API_KEY}"
}
# Make the GET request
response = requests.get(URL, headers=headers)
# Handle the response
if response.status_code == 200:
data = response.json()
print("Total Clips:", data["count"])
print("Current Page:", data["current"])
print("Total Pages:", data["total_pages"])
print("Results:")
for clip in data["results"]:
print(f"- Key: {clip['key']}")
print(f" Name: {clip['name']}")
print(f" Created Date: {clip['created_date']}")
print(f" Duration: {clip['duration']} seconds")
print(f" Audio File Upload: {clip['audio_file_upload']}")
print("")
else:
print("Failed to retrieve clips.")
print("Status Code:", response.status_code)
print("Response:", response.text)
const axios = require('axios');
const API_KEY = "MY_API_KEY"; // Replace this with your actual API key
const URL = "https://api.soundmadeseen.com/public/v1/clips/";
// Headers
const headers = {
"Authorization": `Api-Key ${API_KEY}`
};
// Make the GET request
axios
.get(URL, { headers })
.then(response => {
if (response.status === 200) {
const data = response.data;
console.log("Total Clips:", data.count);
console.log("Current Page:", data.current);
console.log("Total Pages:", data.total_pages);
console.log("Results:");
data.results.forEach(clip => {
console.log(`- Key: ${clip.key}`);
console.log(` Name: ${clip.name}`);
console.log(` Created Date: ${clip.created_date}`);
console.log(` Duration: ${clip.duration} seconds`);
console.log(` Audio File Upload: ${clip.audio_file_upload}`);
console.log("");
});
} else {
console.error("Failed to retrieve clips.");
console.error("Status Code:", response.status);
console.error("Response:", response.data);
}
})
.catch(error => {
if (error.response) {
console.error("Error response:", error.response.status, error.response.data);
} else {
console.error("Error:", error.message);
}
});
curl -X GET https://api.soundmadeseen.com/public/v1/clips/ \
-H "Authorization: Api-Key MY_API_KEY"
<?php
// Replace with your actual API key
$apiKey = "MY_API_KEY";
$url = "https://api.soundmadeseen.com/public/v1/clips/";
// Initialize cURL
$ch = curl_init();
// Set cURL options
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Api-Key $apiKey"
],
]);
// Execute the request
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// Check for errors
if (curl_errno($ch)) {
echo "cURL Error: " . curl_error($ch);
} else {
if ($httpCode === 200) {
$data = json_decode($response, true);
echo "Total Clips: " . $data["count"] . "\n";
echo "Current Page: " . $data["current"] . "\n";
echo "Total Pages: " . $data["total_pages"] . "\n";
echo "Results:\n";
foreach ($data["results"] as $clip) {
echo "- Key: " . $clip["key"] . "\n";
echo " Name: " . $clip["name"] . "\n";
echo " Created Date: " . $clip["created_date"] . "\n";
echo " Duration: " . $clip["duration"] . " seconds\n";
echo " Audio File Upload: " . $clip["audio_file_upload"] . "\n\n";
}
} else {
echo "Failed to retrieve clips. HTTP Code: $httpCode\n";
echo "Response: " . $response . "\n";
}
}
// Close cURL session
curl_close($ch);
Clip Status
GET
https://api.soundmadeseen.com/public/v1/clips/clip_key/status/
This endpoint can be used to check the status of a clip and is particularly useful to check after a clip has been generated using the Create a clip endpoint. The response contains a status field which may have a value of pending, error or completed.
This endpoint accepts the following path parameters:
- upload_key - the key or identifier of this upload.
Responses
A successful response will have an HTTP status code of 200 and will look similar to the following (once the clip has been generated and fully processed):
{
"key": "Zk74kjXdFLekwWDdPZhDpr",
"audio_file_upload": "MFeBLAYGhUwEt6i3SriWKB",
"created_date": "2025-01-25T02:49:05.299742Z",
"name": "Demonstration clip",
"original_end": 115.5,
"original_start": 0,
"duration": 115.5,
"status": "completed"
}
If a clip with the specified clip_key can not be found, the response will have an HTTP status code of 404.
Following are some code examples:
Code examples
import requests
# Replace these with your actual values
API_KEY = "MY_API_KEY"
CLIP_KEY = "<clip_key>" # Replace with the actual clip key
URL = f"https://api.soundmadeseen.com/public/v1/clips/{CLIP_KEY}/status/"
# Headers
headers = {
"Authorization": f"Api-Key {API_KEY}"
}
# Make the GET request
response = requests.get(URL, headers=headers)
# Handle the response
if response.status_code == 200:
data = response.json()
print("Clip Key:", data["key"])
print("Name:", data["name"])
print("Audio File Upload Key:", data["audio_file_upload"])
print("Created Date:", data["created_date"])
print("Original Start:", data["original_start"], "seconds")
print("Original End:", data["original_end"], "seconds")
print("Duration:", data["duration"], "seconds")
print("Status:", data["status"])
else:
print("Failed to retrieve clip status.")
print("Status Code:", response.status_code)
print("Response:", response.text)
const axios = require('axios');
// Replace these with your actual values
const API_KEY = "MY_API_KEY";
const CLIP_KEY = "<clip_key>"; // Replace with the actual clip key
const URL = `https://api.soundmadeseen.com/public/v1/clips/${CLIP_KEY}/status/`;
// Headers
const headers = {
"Authorization": `Api-Key ${API_KEY}`
};
// Make the GET request
axios
.get(URL, { headers })
.then(response => {
if (response.status === 200) {
const data = response.data;
console.log("Clip Key:", data.key);
console.log("Name:", data.name);
console.log("Audio File Upload Key:", data.audio_file_upload);
console.log("Created Date:", data.created_date);
console.log("Original Start:", data.original_start, "seconds");
console.log("Original End:", data.original_end, "seconds");
console.log("Duration:", data.duration, "seconds");
console.log("Status:", data.status);
} else {
console.error("Unexpected response:", response.status, response.data);
}
})
.catch(error => {
if (error.response) {
console.error("Error response:", error.response.status, error.response.data);
} else {
console.error("Error:", error.message);
}
});
curl -X GET https://api.soundmadeseen.com/public/v1/clips/<clip_key>/status/ \
-H "Authorization: Api-Key MY_API_KEY"
<?php
// Replace with your actual API key and clip key
$apiKey = "MY_API_KEY";
$clipKey = "<clip_key>"; // Replace with the actual clip key
$url = "https://api.soundmadeseen.com/public/v1/clips/$clipKey/status/";
// Initialize cURL
$ch = curl_init();
// Set cURL options
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Api-Key $apiKey"
],
]);
// Execute the request
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// Check for errors
if (curl_errno($ch)) {
echo "cURL Error: " . curl_error($ch);
} else {
if ($httpCode === 200) {
$data = json_decode($response, true);
echo "Clip Key: " . $data["key"] . "\n";
echo "Name: " . $data["name"] . "\n";
echo "Audio File Upload Key: " . $data["audio_file_upload"] . "\n";
echo "Created Date: " . $data["created_date"] . "\n";
echo "Original Start: " . $data["original_start"] . " seconds\n";
echo "Original End: " . $data["original_end"] . " seconds\n";
echo "Duration: " . $data["duration"] . " seconds\n";
echo "Status: " . $data["status"] . "\n";
} else {
echo "Failed to retrieve clip status. HTTP Code: $httpCode\n";
echo "Response: " . $response . "\n";
}
}
// Close cURL session
curl_close($ch);
Clip transcription status
GET
https://api.soundmadeseen.com/public/v1/clips/clip_key/transcription/
This endpoint can be used to check the status and retrieve the text of a clip's transcription.
This endpoint accepts the following path parameters:
- clip_key - the key or identifier of this clip.
Response
A successful response will return HTTP status code 200 and will return a JSON object similar to the following:
{
"engine": "manual",
"status": "imported",
"language_code": "en",
"created_date": "2025-01-25T02:49:17.161332Z",
"text": "The text of the transcription will appear in this field"
}
If a clip cannot be found with the provided key, a response with HTTP status code 404 will be returned with the following JSON output:
{
"success": false,
"error": "Clip not found"
}
If a clip is found, but does not have a transcription, a response with HTTP status code 404 will be returned with the following JSON output:
{
"success": false,
"error": "Transcription not found"
}
Read on for code examples:
Code examples
import requests
# Replace these with your actual values
API_KEY = "MY_API_KEY"
CLIP_KEY = "<clip_key>" # Replace with the actual clip key
URL = f"https://api.soundmadeseen.com/public/v1/clips/{CLIP_KEY}/transcription/"
# Headers
headers = {
"Authorization": f"Api-Key {API_KEY}"
}
# Make the GET request
response = requests.get(URL, headers=headers)
# Handle the response
if response.status_code == 200:
data = response.json()
print("Transcription Details:")
print("Engine:", data["engine"])
print("Status:", data["status"])
print("Language Code:", data["language_code"])
print("Created Date:", data["created_date"])
print("Text:", data["text"])
else:
print("Failed to retrieve transcription.")
print("Status Code:", response.status_code)
print("Response:", response.text)
const axios = require('axios');
// Replace these with your actual values
const API_KEY = "MY_API_KEY";
const CLIP_KEY = "<clip_key>"; // Replace with the actual clip key
const URL = `https://api.soundmadeseen.com/public/v1/clips/${CLIP_KEY}/transcription/`;
// Headers
const headers = {
"Authorization": `Api-Key ${API_KEY}`
};
// Make the GET request
axios
.get(URL, { headers })
.then(response => {
if (response.status === 200) {
const data = response.data;
console.log("Transcription Details:");
console.log("Engine:", data.engine);
console.log("Status:", data.status);
console.log("Language Code:", data.language_code);
console.log("Created Date:", data.created_date);
console.log("Text:", data.text);
} else {
console.error("Unexpected response:", response.status, response.data);
}
})
.catch(error => {
if (error.response) {
console.error("Error response:", error.response.status, error.response.data);
} else {
console.error("Error:", error.message);
}
});
curl -X GET https://api.soundmadeseen.com/public/v1/clips/<clip_key>/transcription/ \
-H "Authorization: Api-Key MY_API_KEY"
<?php
// Replace with your actual API key and clip key
$apiKey = "MY_API_KEY";
$clipKey = "<clip_key>"; // Replace with the actual clip key
$url = "https://api.soundmadeseen.com/public/v1/clips/$clipKey/transcription/";
// Initialize cURL
$ch = curl_init();
// Set cURL options
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Api-Key $apiKey"
],
]);
// Execute the request
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// Check for errors
if (curl_errno($ch)) {
echo "cURL Error: " . curl_error($ch);
} else {
if ($httpCode === 200) {
$data = json_decode($response, true);
echo "Transcription Details:\n";
echo "Engine: " . $data["engine"] . "\n";
echo "Status: " . $data["status"] . "\n";
echo "Language Code: " . $data["language_code"] . "\n";
echo "Created Date: " . $data["created_date"] . "\n";
echo "Text: " . $data["text"] . "\n";
} else {
echo "Failed to retrieve transcription. HTTP Code: $httpCode\n";
echo "Response: " . $response . "\n";
}
}
// Close cURL session
curl_close($ch);
Upload a transcription for a clip
POST
https://api.soundmadeseen.com/public/v1/clips/clip_key/transcription/
This endpoint can be used to upload an SRT or VTT file which will be used as a transcription for the clip with the specified clip_key.
The body of this request should be set to multipart/form-data to enable file uploading.
This endpoint accepts the following path parameters:
- clip_key - the key or identifier for this clip.
The body of the request must contain the following field:
- file - the file to upload. This file must be in SRT or VTT format and can be a maximum of 250kb in size.
The body of the request may also contain the following field:
- language_code - the language code of the transcription. This must be a language code as specified in our acceptable language codes list. Defaults to en (English)
If a transcription is already associated with this clip, it will be deleted and replaced with the uploaded transcription.
Response
If successful, a response will return an HTTP status code of 200, with a json response similar to the following:
{
"engine": "API file upload",
"status": "imported",
"language_code": "en_au",
"created_date": "2024-12-15T02:03:35.141011Z",
"text": "This field contains the text of the transcription"
}
If a clip with the associated key can not be found, a response with an HTTP status code of 404 will be returned.
Other error responses will be in the 400 range and will have an output similar to the following:
{
"success": "false",
"error": "Invalid file type"
}
Read on for even more example code!
Code examples
import requests
# Replace these with your actual values
API_KEY = "MY_API_KEY"
CLIP_KEY = "<clip_key>" # Replace with the actual clip key
FILE_PATH = "path/to/your/file.srt" # Replace with the path to your SRT or VTT file
URL = f"https://api.soundmadeseen.com/public/v1/clips/{CLIP_KEY}/transcription/"
# Headers
headers = {
"Authorization": f"Api-Key {API_KEY}"
}
# Prepare the file for upload
with open(FILE_PATH, "rb") as file:
files = {
"file": file
}
# Make the POST request
response = requests.post(URL, headers=headers, files=files)
# Handle the response
if response.status_code == 200:
data = response.json()
print("Upload successful!")
print("Engine:", data["engine"])
print("Status:", data["status"])
print("Language Code:", data["language_code"])
print("Created Date:", data["created_date"])
print("Text:", data["text"])
else:
print("Failed to upload file.")
print("Status Code:", response.status_code)
print("Response:", response.text)
const axios = require('axios');
const fs = require('fs');
const FormData = require('form-data');
// Replace these with your actual values
const API_KEY = "MY_API_KEY";
const CLIP_KEY = "<clip_key>"; // Replace with the actual clip key
const FILE_PATH = "path/to/your/file.srt"; // Replace with the path to your SRT or VTT file
const URL = `https://api.soundmadeseen.com/public/v1/clips/${CLIP_KEY}/transcription/`;
// Create a FormData instance
const formData = new FormData();
formData.append('file', fs.createReadStream(FILE_PATH));
// Headers
const headers = {
...formData.getHeaders(),
"Authorization": `Api-Key ${API_KEY}`
};
// Make the POST request
axios
.post(URL, formData, { headers })
.then(response => {
if (response.status === 200) {
const data = response.data;
console.log("Upload successful!");
console.log("Engine:", data.engine);
console.log("Status:", data.status);
console.log("Language Code:", data.language_code);
console.log("Created Date:", data.created_date);
console.log("Text:", data.text);
} else {
console.error("Unexpected response:", response.status, response.data);
}
})
.catch(error => {
if (error.response) {
console.error("Error response:", error.response.status, error.response.data);
} else {
console.error("Error:", error.message);
}
});
curl -X POST https://api.soundmadeseen.com/public/v1/clips/<clip_key>/transcription/ \
-H "Authorization: Api-Key MY_API_KEY" \
-F "file=@/path/to/your/file.srt"
<?php
// Replace with your actual API key and clip key
$apiKey = "MY_API_KEY";
$clipKey = "<clip_key>"; // Replace with the actual clip key
$filePath = "path/to/your/file.srt"; // Replace with the path to your SRT or VTT file
$url = "https://api.soundmadeseen.com/public/v1/clips/$clipKey/transcription/";
// Initialize cURL
$ch = curl_init();
// Prepare file for upload
$file = new CURLFile($filePath);
// Set cURL options
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Api-Key $apiKey"
],
CURLOPT_POSTFIELDS => [
"file" => $file
],
]);
// Execute the request
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
// Check for errors
if (curl_errno($ch)) {
echo "cURL Error: " . curl_error($ch);
} else {
if ($httpCode === 200) {
$data = json_decode($response, true);
echo "Upload successful!\n";
echo "Engine: " . $data["engine"] . "\n";
echo "Status: " . $data["status"] . "\n";
echo "Language Code: " . $data["language_code"] . "\n";
echo "Created Date: " . $data["created_date"] . "\n";
echo "Text: " . $data["text"] . "\n";
} else {
echo "Failed to upload file. HTTP Code: $httpCode\n";
echo "Response: " . $response . "\n";
}
}
// Close cURL session
curl_close($ch);
