KINTSUGI VOICE STACK INTRO
SDKS
ZOOM
AUDIO FILE SPECIFICATION

Kintsugi Signal API (v2) — Developer Docs

About

Kintsugi Signal provides real-time, voice-based deepfake detection to help organizations identify synthetic or manipulated audio in high-risk communication environments.

Using proprietary voice intelligence models, the Signal API analyzes audio and returns a normalized deepfake risk score, enabling teams to surface potential impersonation or fraud signals within their existing security, trust, and review workflows.

This documentation introduces the Signal API at a high level and is designed to complement our autogenerated Swagger reference by providing additional context, guidance, and visual examples for interpreting results.

Understanding the Deepfake Score

Kintsugi Signal returns a Deepfake Risk Score on a 0-100 scale, indicating the likelihood that a voice sample is synthetic or manipulated.

‍0 → Audio is highly likely to be authentic
‍100 → Audio is highly likely to be synthetic or manipulated

The score is intended to be used as a decision-support signal, not a standalone determination. Customers typically combine this output with other contextual, behavioral, or security indicators when making downstream decisions.

NOTE
Thresholds and response actions may vary based on customer risk tolerance and use case.

Base URL

POST https://api.kintsugihealth.com/v2/initate

Authentication

All requests to the Kintsugi Signal API require an API key issued by Kintsugi

Obtaining an API Key

API keys are provisioned manually. To request access, contact engineering@kintsugihealth.com

Request Header

X-API-Key: <YOUR_API_KEY>
NOTE
Thresholds and response actions may vary based on customer risk tolerance and use case.

Quickstart: End-to-end flow

Kintsugi Signal’s prediction workflow follows a simple sequence:

1.  Initiate a session (and confirm user consent, if applicable)
2. Submit audio for analysis (non-blocking)
3. Get results using the session identifier (poll until ready)

Initiate a Session

Creates a session identifier that ties together metadata, submitted audio, and analysis results. Each session is associated with a single prediction. Create a new session for each analysis.

Endpoint

POST /initiate

Headers

X-API-Key: <YOUR_API_KEY>

Request body (example)

{

  "user_id": "user-123",

  "is_initiated": true,

}

Reponse Fields

session_id — Unique identifier for the analysis session.

Response (example)

{

  "session_id": "sess_abc123"

}

Submit Audio for Analysis

Submits a voice sample for analysis. This call is a non-blocking; use the "Get results' endpoint to retrieve outputs

Endpoint

POST /predict

Request

Include the session_id
Include the audio payload per the Audio File Specification (codec/format/length requirements)

Request body (example)

{

  "session_id": "sess_abc123",

  "status": "processing"

}

Get Results

Retrieves deepfake detection results associated with a session. You may need to poll until the result is ready.

Endpoint

POST /predict

Response

NAME

VALUE

DESCRIPTION

200

N/A

OK — Request processed successfully

401

{
  "message": "string
}

Unauthorized — Not authorized to access this resource

403

{
 "message": "string
}

Forbidden — Not authenticated

404

{
  "message": "string
}

Not Found — Session does not exist

417

{
  "message": "string
}

Expectation Failed — Request did not meet processing requirements

422

{
  "message": "string
}

Unprocessable Entity — Validation error in request data

500

{
  "message": "string
}

Internal Server Error — Server encountered an unexpected condition

Request (example)

{

  "created_at": "2025-12-29 02:15:38",

  "disclaimer": "",

  "is_calibrated": false,

  "model_category": "deepfake",

  "model_granularity": "severity",

  "predicted_is_deepfake": false,

  "predicted_deepfake_score": 2,

  "predicted_score": "false",

  "status": "success",

  "updated_at": "2025-12-29 02:16:38"

}

Errors

Typical errors include:
Missing API key → invalid request error
Invalid API key → authentication error

Sample code of the complete flow

JavaScript: Binary
JavaScript: Severity
Python: Binary
Python: Severity

import fetch from 'node-fetch'
import FormData from 'form-data'
import fs from 'fs'
import path from 'path'


const API_KEY = 'your api key'
const USER_ID = 'user_id from your system'
const VOICE_SAMPLE = path.resolve('Sub_PHQ0_GAD0_I.wav')

// Create authentication headers.
const headers = {'X-API-Key': API_KEY}

// Initiate session between the patient and a doctor.
const initiateFormData = new FormData()
initiateFormData.append('user_id', USER_ID)
initiateFormData.append('is_initiated', 'true') // Send boolean as string in form data
const initiateResp = await fetch('https://api.kintsugihealth.com/v1/initiate', {
  method: 'POST',
  headers: { ...headers, ...initiateFormData.getHeaders() },
  body: initiateFormData,
})

if (!initiateResp.ok) {
  throw new Error(`HTTP error! status: ${initiateResp.status}`)
}


// Fetch session_id, it will be used as an identifier to make a prediction and provide feedback.
let initiateData = await initiateResp.json()
const sessionID = initiateData.session_id


// *Binary: Make a prediction for the specified patient's voice sample.
const predictionFormData = new FormData()
predictionFormData.append('file', fs.createReadStream(VOICE_SAMPLE))
predictionFormData.append('session_id', sessionID)
let predictionResp = await fetch('https://api.kintsugihealth.com/v1/predict/server/depression/binary', {
  method: 'POST',
  headers: { ...headers, ...predictionFormData.getHeaders() },
  body: predictionFormData
})

if (!predictionResp.ok) {
  throw new Error(`HTTP error! status: ${predictionResp.status}`)
}


// *PHQ-2: Provide a doctor's feedback on the quality of the prediction.
let feedbackResp = await fetch('https://api.kintsugihealth.com/v1/feedback/server/phq/2', {
  method: 'PATCH',
  headers: {...headers, 'Content-Type': 'application/json'},
  body: JSON.stringify({'session_id': sessionID, 'actual_score': [1, 2]})
})

if (!feedbackResp.ok) {
  throw new Error(`HTTP error! status: ${feedbackResp.status}`)
}


// *PHQ-9: Provide a doctor's feedback on the quality of the prediction.
feedbackResp = await fetch('https://api.kintsugihealth.com/v1/feedback/server/phq/9', {
  method: 'PATCH',
  headers: {...headers, 'Content-Type': 'application/json'},
  body: JSON.stringify({'session_id': sessionID, 'actual_score': [1, 2, 3, 1, 2, 3, 1, 2, 3]})
})

if (!feedbackResp.ok) {
  throw new Error(`HTTP error! status: ${feedbackResp.status}`)
}


// *Binary: Provide a doctor's feedback on the quality of the prediction.
const feedbackFormData = new FormData()
feedbackFormData.append('session_id', sessionID)
feedbackFormData.append('actual_score', 'true')
feedbackResp = await fetch('https://api.kintsugihealth.com/v1/feedback/server/depression/binary', {
  method: 'PATCH',
  headers: { ...headers, ...feedbackFormData.getHeaders() },
  body: feedbackFormData,
})

if (!feedbackResp.ok) {
  throw new Error(`HTTP error! status: ${feedbackResp.status}`)
}

console.log('The prediction was completed successfully!')
        



import fetch from 'node-fetch'
import FormData from 'form-data'
import fs from 'fs'
import path from 'path'


const API_KEY = 'your api key'
const USER_ID = 'user_id from your system'
const VOICE_SAMPLE = path.resolve('Sub_PHQ0_GAD0_I.wav')

// Create authentication headers.
const headers = {'X-API-Key': API_KEY}

// Initiate session between the patient and a doctor.
const initiateFormData = new FormData()
initiateFormData.append('user_id', USER_ID)
initiateFormData.append('is_initiated', 'true') // Send boolean as string in form data
const initiateResp = await fetch('https://api.kintsugihealth.com/v1/initiate', {
  method: 'POST',
  headers: { ...headers, ...initiateFormData.getHeaders() },
  body: initiateFormData,
})

if (!initiateResp.ok) {
  throw new Error(`HTTP error! status: ${initiateResp.status}`)
}


// Fetch session_id, it will be used as an identifier to make a prediction and provide feedback.
let initiateData = await initiateResp.json()
const sessionID = initiateData.session_id


// Severity: Make a prediction for the specified patient's voice sample.
const predictionFormData = new FormData()
predictionFormData.append('file', fs.createReadStream(VOICE_SAMPLE))
predictionFormData.append('session_id', sessionID)
let predictionResp = await fetch('https://api.kintsugihealth.com/v1/predict/server/depression/severity', {
  method: 'POST',
  headers: { ...headers, ...predictionFormData.getHeaders() },
  body: predictionFormData
})

if (!predictionResp.ok) {
  throw new Error(`HTTP error! status: ${predictionResp.status}`)
}


// *PHQ-2: Provide a doctor's feedback on the quality of the prediction.
let feedbackResp = await fetch('https://api.kintsugihealth.com/v1/feedback/server/phq/2', {
  method: 'PATCH',
  headers: {...headers, 'Content-Type': 'application/json'},
  body: JSON.stringify({'session_id': sessionID, 'actual_score': [1, 2]})
})

if (!feedbackResp.ok) {
  throw new Error(`HTTP error! status: ${feedbackResp.status}`)
}


// *PHQ-9: Provide a doctor's feedback on the quality of the prediction.
feedbackResp = await fetch('https://api.kintsugihealth.com/v1/feedback/server/phq/9', {
  method: 'PATCH',
  headers: {...headers, 'Content-Type': 'application/json'},
  body: JSON.stringify({'session_id': sessionID, 'actual_score': [1, 2, 3, 1, 2, 3, 1, 2, 3]})
})

if (!feedbackResp.ok) {
  throw new Error(`HTTP error! status: ${feedbackResp.status}`)
}

console.log('The prediction was completed successfully!')
        



import requests

API_KEY = '<your api key>'
USER_ID = '<user_id from your system>'
VOICE_SAMPLE = "Sub_PHQ0_GAD0_I.wav"

# Create an HTTP Client. Provide authentication credentials.
session = requests.Session()
session.headers.update({"X-API-Key": API_KEY})

# Initiate session between the patient and a doctor.
initiate_resp = session.post(
    url="https://api.kintsugihealth.com/v1/initiate",
    data={"user_id": USER_ID, "is_initiated": True},
)
initiate_resp.raise_for_status()

# Fetch session_id, it will be used as an identifier to make a prediction and provide feedback.
session_id = initiate_resp.json()["session_id"]

# Make a prediction for the specified patient's voice sample.
with open(VOICE_SAMPLE, 'rb') as patient_voice_sample:
    prediction_resp = session.post(
        url="https://api.kintsugihealth.com/v1/predict/server/depression/binary",
        files={'file': patient_voice_sample},
        data={"session_id": session_id},
    )
    prediction_resp.raise_for_status()

# *PHQ-2: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/2",
    json={"session_id": session_id, "actual_score": [1, 2]},
)
feedback_resp.raise_for_status()

# *PHQ-9: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/9",
    json={"session_id": session_id, "actual_score": [1, 2, 3, 1, 2, 3, 1, 2, 3]},
)
feedback_resp.raise_for_status()

# *Binary: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/depression/binary",
    data={"session_id": session_id, "actual_score": "true"},
)
feedback_resp.raise_for_status()

print("The prediction was completed successfully!")



import requests

API_KEY = '<your api key>'
USER_ID = '<user_id from your system>'
VOICE_SAMPLE = "Sub_PHQ0_GAD0_I.wav"

# Create an HTTP Client. Provide authentication credentials.
session = requests.Session()
session.headers.update({"X-API-Key": API_KEY})

# Initiate session between the patient and a doctor.
initiate_resp = session.post(
    url="https://api.kintsugihealth.com/v1/initiate",
    data={"user_id": USER_ID, "is_initiated": True},
)
initiate_resp.raise_for_status()

# Fetch session_id, it will be used as an identifier to make a prediction and provide feedback.
session_id = initiate_resp.json()["session_id"]

# Make a prediction for the specified patient's voice sample.
with open(VOICE_SAMPLE, 'rb') as patient_voice_sample:
    prediction_resp = session.post(
        url="https://api.kintsugihealth.com/v1/predict/server/depression/severity",
        files={'file': patient_voice_sample},
        data={"session_id": session_id},
    )
    prediction_resp.raise_for_status()

# *PHQ-2: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/2",
    json={"session_id": session_id, "actual_score": [1, 2]},
)
feedback_resp.raise_for_status()

# *PHQ-9: Provide a doctor's feedback on the quality of the prediction.
feedback_resp = session.patch(
    url="https://api.kintsugihealth.com/v1/feedback/server/phq/9",
    json={"session_id": session_id, "actual_score": [1, 2, 3, 1, 2, 3, 1, 2, 3]},
)
feedback_resp.raise_for_status()

print("The prediction was completed successfully!")