API Documentation

AI Audio Detection API

Complete documentation for integrating TruthScan's AI audio detection API into your applications.

Try it out without code by visiting our FastAPI endpoint: https://detect-audio.truthscan.com/docs

Authentication

TruthScan uses API keys to allow access to the API. You can get your API key at the top of the page in our developer portal.

TruthScan expects for the API key to be included in all API requests to the server in a request body that looks like the following:

{
  "key": "YOUR API KEY GOES HERE"
}

You must replace YOUR API KEY GOES HERE with your personal API key.

AI Audio Detector

Detect (3-Step Process)

The AI Audio Detection workflow consists of the following steps:

  • Obtain a Pre-signed Upload URL
  • Upload the Audio
  • Submit the Audio for Detection

1. Obtain a Pre-signed Upload URL

Begin by requesting a pre-signed URL from the API. This URL allows you to securely upload your audio file to the storage server.

Supported File Formats

MP3, WAV, M4A, FLAC, OGG

Important Note

It is necessary to remove spaces from the audio filename when requesting a pre-signed URL.

GET https://detect-audio.truthscan.com/get-presigned-url?file_name=example.mp3

Example Request

curl -X GET 'https://detect-audio.truthscan.com/get-presigned-url?file_name=example.mp3' \
--header 'apikey: YOUR API KEY GOES HERE'

Example Response

{
  "status": "success",
  "presigned_url": "https://nyc3.digitaloceanspaces.com/ai-audio-detector-prod/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...",
  "file_path": "https://ai-audio-detector-prod.nyc3.digitaloceanspaces.com/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250901-090201_example.mp3"
}

2. Upload the Audio

Use the provided 'presigned_url' to upload your audio via a PUT request. Ensure the correct content type is set according to your audio format.

Important Note

It is necessary to remove spaces from the audio filename when uploading the audio.

Example Request

curl -X PUT 'https://nyc3.digitaloceanspaces.com/ai-audio-detector-prod/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...' \
  --header 'Content-Type: audio/<FILE_FORMAT - mp3, wav, m4a, flac, ogg>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.mp3' # Attachment

File Size Limits

  • Minimum file size: 1KB
  • Maximum file size: 10MB

Ensure that the file format remains consistent during the upload process. A successful upload will return a status code of 200.

3. Submit Audio for AI Detection

After uploading, submit the audio for AI detection by referencing the 'file_path' from the previous step.

POST https://detect-audio.truthscan.com/detect

Example Request

curl -X 'POST' \
  'https://detect-audio.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "<FILE_PATH>",
  "document_type": "Audio",
  "analyzeUpToSeconds": 60
}'

The 'FILE_PATH' refers to the path obtained from the response in the initial step, 'Obtain a Pre-signed Upload URL'.

Optional Parameters

  • analyzeUpToSeconds: Analyze up to N seconds from the beginning (default: 60)
  • document_type: Type of document (default: 'Audio')
  • email: Optional email for processing

Example Response

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending"
}

The response includes a unique ID for tracking the detection status.

Query Detection Status and Results

To check the status and retrieve the results, use the /query endpoint with the ID.

POST https://detect-audio.truthscan.com/query

Example Request

curl -X 'POST' \
  'https://detect-audio.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "ID-GOES-HERE"
}'

Example Response

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 0.873,
    "result_details": {
        "is_valid": true,
        "message": "processed",
        "original_duration": 123.45,
        "is_truncated": true,
        "truncated_duration": 60.0,
        "mean_ai_prob": 0.873,
        "individual_chunks_ai_prob": [0.81, 0.90, 0.91]
    }
}

Result Details

  • is_valid: Indicates if the audio file is valid (true/false)
  • message: Processing message
  • original_duration: Duration in seconds of the original audio
  • is_truncated: Whether the audio was truncated for analysis
  • truncated_duration: Duration analyzed if truncated
  • mean_ai_prob: Overall AI probability score
  • individual_chunks_ai_prob: Per-chunk AI probability scores

The "status" field will be one of: "pending" (processing is queued), "analyzing" (AI detection is in progress), "done" (results are available), or "failed" (processing failed).

Check User Credits

This endpoint accepts the users apikey via the header. And returns users credit details.

GET https://detect-audio.truthscan.com/check-user-credits

Example Request

curl -X 'GET' \
  'https://detect-audio.truthscan.com/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

Example Response

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

Health Check

Check the health status of the API server.

GET https://detect-audio.truthscan.com/health

Example Request

curl -X 'GET' \
  'https://detect-audio.truthscan.com/health' \
  -H 'accept: application/json'

Example Response

{
    "status": "healthy"
}

Errors

Most errors will be from incorrect parameters being sent to the API. Double check the parameters of each API call to make sure it's properly formatted, and try running the provided example code.

The generic error codes we use conform to the REST standard:

Error CodeMeaning
400Bad Request -- Your request is invalid.
403Forbidden -- The API key is invalid, or there aren't sufficient credits for audio processing.
404Not Found -- The specified resource doesn't exist.
405Method Not Allowed -- You tried to access a resource with an invalid method.
406Not Acceptable -- You requested a format that isn't JSON.
410Gone -- The resource at this endpoint has been removed.
422Invalid Request Body -- Your request body is formatted incorrectly or invalid or has missing parameters.
429Too Many Requests -- You're sending too many requests! Slow it down!
500Internal Server Error -- We had a problem with our server. Try again later.
503Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Common Issues and Solutions

Authentication Issues

"User verification failed" (403)

Cause: Invalid or expired API key

Solution:

  1. Verify your API key is correct
  2. Check if your API key is active in your account
  3. Try regenerating your API key

"Not enough credits" (403)

Cause: Insufficient credits for audio processing

Solution:

  1. Check your remaining credits using /check-user-credits
  2. Purchase additional credits if needed
  3. Use analyzeUpToSeconds to analyze less audio and consume fewer credits

Input Validation Issues

"Unsupported file format" (400)

Cause: Unsupported or invalid audio format submitted

Solution:

  1. Verify audio format is supported (MP3, WAV, M4A, FLAC, OGG)
  2. Ensure the file is not corrupted
  3. Check Content-Type header when uploading

"File too large" (400)

Cause: File size exceeds 10MB limit

Solution:

  1. Compress or convert the audio to under 10MB
  2. Check file size before uploading
  3. Use more efficient formats like MP3 when possible

Processing Issues

"Audio processing took too long"

Cause: Audio processing took too long or timeout occurred

Solution:

  1. Try with a smaller audio file or shorter duration
  2. Use analyzeUpToSeconds to analyze only the first seconds
  3. Check if the service is experiencing high load
  4. Retry the request after a few minutes

Status "failed" in /query response

Cause: Processing failed for various reasons

Solution:

  1. Check if audio meets minimum requirements (1KB - 10MB)
  2. Verify audio is in a supported format
  3. Verify upload completed successfully before submitting for detection
  4. Contact support if issue persists

Upload Issues

"Audio upload failed" (403/400)

Cause: Invalid or expired pre-signed URL, or issues with storage server

Solution:

  1. Ensure you use the pre-signed URL immediately after receiving it (may expire)
  2. Verify Content-Type header is correct for audio format
  3. Remove spaces from filename before uploading
  4. Try generating a new pre-signed URL if the current one expired

"Invalid pre-signed URL" (400)

Cause: Filename with spaces or expired/corrupted pre-signed URL

Solution:

  1. Remove all spaces from filename before requesting pre-signed URL
  2. Use only alphanumeric characters, hyphens and underscores in filename
  3. Generate a new pre-signed URL if needed

Need Help?

For more information about using our API or for technical support, please contact us.

Contact Us

API Frequently Asked Questions

Find answers to the most common questions about our AI audio detection API.

You can get your API key by visiting your account in the TruthScan developer portal. The API key is available at the top of your account page.