Documentation

File Upload Endpoints

Upload a File Upload

POST 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()}")

List File Uploads

GET 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}")

File Upload Status

GET 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}")

File Upload transcription status

GET 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}")

Upload a transcription for a file upload

POST 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)

Envoyer des commentaires