Documentation
File Upload Endpoints
Upload a File Upload
https://api.soundmadeseen.com/public/v1/upload/
The body of this request should be set to multipart/form-data to enable file uploading.
The body of the request must contain the following field:
- file - the file to upload. The file can be in WAV, MP3, FLAC, MP4 or MOV format. The file must also be less than 750MB in size.
The body of the request may contain the following optional fields:
- transcribe - if set to true, the upload will be transcribed after it has been completely uploaded and processed.
- language_code - the language code to transcribe to. Here is a list of currently acceptable language codes.
- number_of_speakers - if known, the number of speakers in this audio.
Response
If successful, the response will return an HTTP status code of 201. The response will contain a Json object similar to the example below:
{
"upload_key": ID_KEY_OF_NEW_UPLOAD,
"success": True,
}
The returned upload_key can be used to check the status of an uploaded file with the File Upload Status endpoint. If the transcribe parameter is set to true, then the status of the uploaded file's transcription can be checked with the File Upload Transcription Status endpoint.
If the request is not successful the response will be returned with an HTTP status code in the 400 range, with an error_message field, such as the following:
{
"success": False,
"error": "File exceeds maximum upload size of 750MB"
}
Here are some examples demonstrating how to use the endpoint:
Exemples de code
import requests
# File to upload
file_path = "path/to/your/file.mp3" # Replace with your file path
# Open the file in binary mode
with open(file_path, "rb") as file:
# Make the POST request
response = requests.post(
"https://api.soundmadeseen.com/public/v1/upload/",
headers={
"Authorization": f"Api-Key MY_API_KEY"
},
files={ # This sets the body to multipart/form-data
"file": file # 'file' is the parameter name expected by the server
},
data={
"transcribe": "true",
"language_code": "en",
"number_of_speakers": "3"
}
)
# Check the response status
if response.status_code == 201:
upload_key = response.json()["upload_key"]
print(f"Upload successful. Key: {upload_key}")
else:
raise Exception(f"Upload failed: {response.json()}")
const axios = require("axios");
const fs = require("fs");
const FormData = require("form-data");
// File to upload
const filePath = "path/to/your/file.mp3"; // Replace with your file path
// Create a FormData instance
const formData = new FormData();
formData.append("file", fs.createReadStream(filePath)); // Attach the file
formData.append("transcribe", "true"); // Add additional data
formData.append("language_code", "en");
formData.append("number_of_speakers", "3");
// Send the POST request
axios.post("https://api.soundmadeseen.com/public/v1/upload/", formData, {
headers: {
...formData.getHeaders(), // Include form-data headers
"Authorization": `Api-Key MY_API_KEY`, // Replace with your API token
},
})
.then((response) => {
if (response.status === 201) {
const uploadKey = response.data.upload_key;
console.log(`Upload successful. Key: ${uploadKey}`);
} else {
console.error("Unexpected response status:", response.status);
}
})
.catch((error) => {
console.error("Upload failed:", error.response?.data || error.message);
});
curl -X POST "https://api.soundmadeseen.com/public/v1/upload/" \
-H "Authorization: Api-Key MY_API_KEY" \
-F "file=@path/to/your/file.mp3" \
-F "transcribe=true" \
-F "language_code=en" \
-F "number_of_speakers=3"
<?php
// File to upload
$filePath = "path/to/your/file.mp3"; // Replace with your file path
// Initialize cURL
$ch = curl_init();
// Set cURL options
curl_setopt($ch, CURLOPT_URL, "https://api.soundmadeseen.com/public/v1/upload/");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Api-Key MY_API_KEY", // Replace with your API token
]);
// Prepare file and data for multipart/form-data
$postFields = [
"file" => new CURLFile($filePath), // Attach the file
"transcribe" => "true",
"language_code" => "en",
"number_of_speakers" => "3",
];
curl_setopt($ch, CURLOPT_POSTFIELDS, $postFields);
// Execute the request
$response = curl_exec($ch);
// Check for errors
if (curl_errno($ch)) {
echo "cURL Error: " . curl_error($ch);
} else {
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($httpStatus === 201) {
$responseData = json_decode($response, true);
$uploadKey = $responseData["upload_key"];
echo "Upload successful. Key: " . $uploadKey . PHP_EOL;
} else {
echo "Upload failed. Response: " . $response . PHP_EOL;
}
}
// Close cURL session
curl_close($ch);
List File Uploads
https://api.soundmadeseen.com/public/v1/uploads/
This endpoint provides a listing of file uploads 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: 'upload_date', 'original_name' or 'filesize'. Defaults to 'upload_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": 1,
"current": 1,
"total_pages": 1,
"page_size": 12,
"start_index": 1,
"end_index": 1,
"extra_params": {
"order": "upload_date",
"dir": "desc"
},
"results": [
{
"key": "HQ4ouwQqgBr2xD2UVY8oco",
"original_name": "Example Upload",
"extension": ".wav",
"filesize": 4084936,
"duration": 2568.907755
"upload_date": "2024-12-08T03:49:26.286228Z",
"upload_type": "audio",
}]
}
Here are a few code examples:
Exemples de code
import requests
# API Key and Endpoint
API_KEY = "MY_API_KEY" # Replace with your actual API key
ENDPOINT = "https://api.soundmadeseen.com/public/v1/uploads/"
try:
# Make the GET request
response = requests.get(
ENDPOINT,
headers={
"Authorization": f"Api-Key {API_KEY}"
},
)
# Check the response status
if response.status_code == 200:
data = response.json()
total_pages = data.get("total_pages", 0)
results = data.get("results", [])
if results:
first_result_key = results[0].get("key", "No key found")
print(f"Uploads retrieved. Total pages: {total_pages}, First Key: {first_result_key}")
else:
print(f"Uploads retrieved, but no results found. Total pages: {total_pages}")
else:
# Raise an exception with detailed information
raise Exception(f"Listing failed: {response.status_code} - {response.json()}")
except requests.RequestException as e:
print(f"An error occurred while making the request: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
const axios = require("axios");
// API Key and Endpoint
const API_KEY = "MY_API_KEY"; // Replace with your actual API key
const ENDPOINT = "https://api.soundmadeseen.com/public/v1/uploads/";
// Function to fetch uploads
async function fetchUploads() {
try {
// Make the GET request
const response = await axios.get(ENDPOINT, {
headers: {
"Authorization": `Api-Key ${API_KEY}`
}
});
// Process the response
if (response.status === 200) {
const data = response.data;
const totalPages = data.total_pages || 0;
const results = data.results || [];
if (results.length > 0) {
const firstResultKey = results[0].key || "No key found";
console.log(`Uploads retrieved. Total pages: ${totalPages}, First Key: ${firstResultKey}`);
} else {
console.log(`Uploads retrieved, but no results found. Total pages: ${totalPages}`);
}
} else {
console.error(`Listing failed: ${response.status} - ${response.statusText}`);
}
} catch (error) {
if (error.response) {
// API error response
console.error(`API Error: ${error.response.status} - ${error.response.data.detail || error.message}`);
} else if (error.request) {
// No response received
console.error("No response received from the API:", error.request);
} else {
// Other errors
console.error("Error:", error.message);
}
}
}
// Call the function
fetchUploads();
curl -X GET "https://api.soundmadeseen.com/public/v1/uploads/" \
-H "Authorization: Api-Key MY_API_KEY"
<?php
// API Key and Endpoint
$apiKey = "MY_API_KEY"; // Replace with your actual API key
$endpoint = "https://api.soundmadeseen.com/public/v1/uploads/";
// Initialize cURL
$ch = curl_init();
// Set cURL options
curl_setopt($ch, CURLOPT_URL, $endpoint);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Api-Key $apiKey"
]);
// Execute the request
$response = curl_exec($ch);
// Check for cURL errors
if (curl_errno($ch)) {
echo "cURL Error: " . curl_error($ch);
curl_close($ch);
exit;
}
// Get the HTTP status code
$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
// Process the response
if ($httpStatus === 200) {
$data = json_decode($response, true); // Decode the JSON response
$totalPages = $data['total_pages'] ?? 0;
$results = $data['results'] ?? [];
if (!empty($results)) {
$firstResultKey = $results[0]['key'] ?? 'No key found';
echo "Uploads retrieved. Total pages: $totalPages, First Key: $firstResultKey" . PHP_EOL;
} else {
echo "Uploads retrieved, but no results found. Total pages: $totalPages" . PHP_EOL;
}
} else {
echo "Listing failed. HTTP Status: $httpStatus. Response: $response" . PHP_EOL;
}
File Upload Status
https://api.soundmadeseen.com/public/v1/uploads/upload_key/status/
This endpoint can be used to check the status of a file upload and is particularly useful to check after a file upload has been uploaded. 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:
{
"key": "MFeBLAYGhUwEt6i3SriWKB",
"status": "completed",
"upload_date": "2024-12-15T02:03:25.471828Z",
"filesize": 41103102,
"duration": 2568.907755
}
If a file upload with the specified key cannot be found, the response will contain an HTTP status code of 404.
Following are some code examples:
Exemples de code
import requests
# Define the base URL and the upload key
BASE_URL = "https://api.soundmadeseen.com/public/v1/uploads"
UPLOAD_KEY = "NpfEUgcG47DhA3LxJZekst" # Replace this with the actual upload key
# Construct the full URL
status_url = f"{BASE_URL}/{UPLOAD_KEY}/status/"
try:
# Make the GET request to fetch the upload status
response = requests.get(status_url)
# Check if the response was successful
if response.status_code == 200:
# Parse the JSON response
data = response.json()
print(f"Upload Key: {data['key']}")
print(f"Status: {data['status']}")
print(f"Upload Date: {data['upload_date']}")
else:
# Handle error responses
print(f"Failed to fetch upload status. HTTP Status Code: {response.status_code}")
print(f"Response: {response.text}")
except requests.RequestException as e:
# Handle connection or other request-related errors
print(f"An error occurred: {e}")
const axios = require('axios');
const BASE_URL = "https://api.soundmadeseen.com/public/v1/uploads";
const UPLOAD_KEY = "NpfEUgcG47DhA3LxJZekst"; // Replace with actual key
const statusUrl = `${BASE_URL}/${UPLOAD_KEY}/status/`;
axios.get(statusUrl)
.then(response => {
const data = response.data;
console.log(`Upload Key: ${data.key}`);
console.log(`Status: ${data.status}`);
console.log(`Upload Date: ${data.upload_date}`);
})
.catch(error => {
if (error.response) {
console.error(`Failed to fetch upload status. HTTP Status Code: ${error.response.status}`);
console.error(`Response: ${error.response.data}`);
} else {
console.error(`An error occurred: ${error.message}`);
}
});
curl -X GET "https://api.soundmadeseen.com/public/v1/uploads/NpfEUgcG47DhA3LxJZekst/status/" \
-H "Authorization: Api-Key MY_API_KEY"
<?php
// Define the base URL and upload key
$baseUrl = "https://api.soundmadeseen.com/public/v1/uploads";
$uploadKey = "NpfEUgcG47DhA3LxJZekst"; // Replace with the actual upload key
// Construct the full URL
$statusUrl = "{$baseUrl}/{$uploadKey}/status/";
// Initialize cURL
$ch = curl_init();
// Set cURL options
curl_setopt($ch, CURLOPT_URL, $statusUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Api-Key {$apiKey}",
"Accept: application/json",
]);
// Execute the request
$response = curl_exec($ch);
// Check for errors
if (curl_errno($ch)) {
echo "cURL error: " . curl_error($ch);
} else {
// Decode the JSON response
$data = json_decode($response, true);
// Check if decoding was successful
if ($data && isset($data['key'], $data['status'], $data['upload_date'])) {
echo "Upload Key: " . $data['key'] . PHP_EOL;
echo "Status: " . $data['status'] . PHP_EOL;
echo "Upload Date: " . $data['upload_date'] . PHP_EOL;
} else {
echo "Failed to fetch or decode the response. Response: " . $response . PHP_EOL;
}
}
// Close the cURL session
curl_close($ch);
File Upload transcription status
https://api.soundmadeseen.com/public/v1/uploads/upload_key/transcription/
This endpoint can be used to check the status and retrieve the text of a file upload's transcription.
This endpoint accepts the following path parameters:
- upload_key - the key or identifier of this upload.
Response
A successful response will return HTTP status code 200 and will return a JSON object similar to the following:
{
"engine": "assemblyai",
"status": "imported",
"language_code": "en_au",
"created_date": "2024-12-15T02:03:35.141011Z",
"text": "This field contains the text of the transcription"
}
If an upload 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": "Upload not found"
}
If an upload 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:
Exemples de code
import requests
# Define the base URL, upload key, and API key
BASE_URL = "https://api.soundmadeseen.com/public/v1/uploads"
UPLOAD_KEY = "NpfEUgcG47DhA3LxJZekst" # Replace with the actual upload key
API_KEY = "your_api_key_here" # Replace with your API key
# Construct the full URL
transcription_url = f"{BASE_URL}/{UPLOAD_KEY}/transcription/"
# Define the headers with the Authorization key
headers = {
"Authorization": f"Api-Key {API_KEY}",
"Accept": "application/json",
}
try:
# Make the GET request
response = requests.get(transcription_url, headers=headers)
# Check for a successful response
if response.status_code == 200:
data = response.json()
print(f"Transcription Engine: {data['engine']}")
print(f"Status: {data['status']}")
print(f"Language Code: {data['language_code']}")
print(f"Created Date: {data['created_date']}")
print(f"Transcription Text:\n{data['text']}")
else:
print(f"Failed to fetch transcription. HTTP Status Code: {response.status_code}")
print(f"Response: {response.text}")
except requests.RequestException as e:
print(f"An error occurred: {e}")
const axios = require('axios');
// Define the base URL, upload key, and API key
const BASE_URL = "https://api.soundmadeseen.com/public/v1/uploads";
const UPLOAD_KEY = "NpfEUgcG47DhA3LxJZekst"; // Replace with the actual upload key
const API_KEY = "your_api_key_here"; // Replace with your API key
// Construct the full URL
const transcriptionUrl = `${BASE_URL}/${UPLOAD_KEY}/transcription/`;
// Function to fetch transcription data
async function fetchTranscription() {
try {
// Make the GET request with the Authorization header
const response = await axios.get(transcriptionUrl, {
headers: {
"Authorization": `Api-Key ${API_KEY}`,
"Accept": "application/json",
},
});
// Handle a successful response
if (response.status === 200) {
const data = response.data;
console.log(`Transcription Engine: ${data.engine}`);
console.log(`Status: ${data.status}`);
console.log(`Language Code: ${data.language_code}`);
console.log(`Created Date: ${data.created_date}`);
console.log(`Transcription Text:\n${data.text}`);
} else {
console.error(`Failed to fetch transcription. HTTP Status Code: ${response.status}`);
}
} catch (error) {
if (error.response) {
console.error(`Error Response: ${error.response.status}`);
console.error(`Error Data: ${error.response.data}`);
} else {
console.error(`An error occurred: ${error.message}`);
}
}
}
// Call the function
fetchTranscription();
curl -X GET "https://api.soundmadeseen.com/public/v1/uploads/NpfEUgcG47DhA3LxJZekst/transcription/" \
-H "Authorization: Api-Key your_api_key_here" \
-H "Accept: application/json"
<?php
// Define the base URL, upload key, and API key
$baseUrl = "https://api.soundmadeseen.com/public/v1/uploads";
$uploadKey = "NpfEUgcG47DhA3LxJZekst"; // Replace with the actual upload key
$apiKey = "your_api_key_here"; // Replace with your actual API key
// Construct the full URL
$transcriptionUrl = "{$baseUrl}/{$uploadKey}/transcription/";
// Initialize cURL
$ch = curl_init();
// Set cURL options
curl_setopt($ch, CURLOPT_URL, $transcriptionUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Return response as a string
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Api-Key {$apiKey}",
"Accept: application/json",
]);
// Execute the request
$response = curl_exec($ch);
// Check for errors
if (curl_errno($ch)) {
echo "cURL error: " . curl_error($ch);
} else {
// Decode the JSON response
$data = json_decode($response, true);
// Check if decoding was successful
if ($data && isset($data['engine'], $data['status'], $data['language_code'], $data['created_date'], $data['text'])) {
echo "Transcription Engine: " . $data['engine'] . PHP_EOL;
echo "Status: " . $data['status'] . PHP_EOL;
echo "Language Code: " . $data['language_code'] . PHP_EOL;
echo "Created Date: " . $data['created_date'] . PHP_EOL;
echo "Transcription Text:\n" . $data['text'] . PHP_EOL;
} else {
echo "Failed to fetch or decode the response. Response: " . $response . PHP_EOL;
}
}
// Close the cURL session
curl_close($ch);
Upload a transcription for a file upload
https://api.soundmadeseen.com/public/v1/uploads/upload_key/transcription/
This endpoint can be used to upload an SRT or VTT file which will be used as a transcription for the file upload with the specified upload_key.
The body of this request should be set to multipart/form-data to enable file uploading.
This endpoint accepts the following path parameters:
- upload_key - the key or identifier for this file upload.
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 file upload, 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 file upload 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 some exciting example code!
Exemples de code
import requests
# Replace these with your actual values
API_KEY = "MY_API_KEY"
UPLOAD_KEY = "upload_key" # Replace with the actual file upload_key
FILE_PATH = "path/to/your/file.srt" # Replace with the actual path to your SRT or VTT file
URL = f"https://api.soundmadeseen.com/public/v1/uploads/{UPLOAD_KEY}/transcription/"
# Set headers and payload
headers = {
"Authorization": f"Api-Key {API_KEY}"
}
# Prepare the file for upload
with open(FILE_PATH, "rb") as file:
files = {
"file": file
}
# Send the POST request
response = requests.post(URL, headers=headers, files=files)
# Check the response
if response.status_code == 200:
print("Upload successful!")
print("Response:", response.json())
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 UPLOAD_KEY = "<upload_key>"; // Replace with the actual upload_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/uploads/${UPLOAD_KEY}/transcription/`;
// Create a FormData instance
const formData = new FormData();
formData.append('file', fs.createReadStream(FILE_PATH));
// Configure 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) {
console.log('Upload successful!');
console.log('Response:', response.data);
} else {
console.log('Unexpected response:', response.status, response.data);
}
})
.catch(error => {
if (error.response) {
console.error('Failed to upload file.');
console.error('Status Code:', error.response.status);
console.error('Response:', error.response.data);
} else {
console.error('Error:', error.message);
}
});
curl -X POST https://api.soundmadeseen.com/public/v1/uploads/<upload_key>/transcription/ \
-H "Authorization: Api-Key MY_API_KEY" \
-F "file=@/path/to/your/file.srt"
<?php
// Replace these with your actual values
$apiKey = "MY_API_KEY";
$uploadKey = "<upload_key>"; // Replace with the actual upload key
$filePath = "path/to/your/file.srt"; // Replace with the path to your SRT or VTT file
$url = "https://api.soundmadeseen.com/public/v1/uploads/$uploadKey/transcription/";
// Initialize cURL
$ch = curl_init();
// Prepare the 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) {
echo "Upload successful!\n";
echo "Response: " . $response;
} else {
echo "Failed to upload file. HTTP Code: $httpCode\n";
echo "Response: " . $response;
}
}
// Close cURL session
curl_close($ch);