DetectifAI Developer API API

{"openapi":"3.1.0","info":{"title":"DetectifAI Developer API","summary":"Detect AI-generated speech and verify speakers by voice.","description":"The DetectifAI developer API detects synthetic (AI-generated) speech and verifies speakers by voice.\n\n**Authentication.** Send your API key in the `Authorization` header: `Authorization: Bearer dtf_live_...`.\nKeys are created in the dashboard and shown once. Never put keys in URLs.\n\n**Credits.** Detection, enrollment and verification use credits from your account balance; your balance is\nshown in the dashboard and at `GET /v1/credits`. Only completed checks use credits: a rejected file, a busy\nservice or a failed check uses none. A verification with `detect_deepfake=true` counts as two checks.\n\n**Uploads.** Send audio as `multipart/form-data` (field `file`), up to 100 MB. The whole upload must arrive\nwithin 120 s (at no less than 64 KB/s); larger or slower uploads are rejected (`413`, `408`). When too many\nlarge uploads are in progress the API answers `503 server_busy` with `Retry-After`. Durations are checked\nafter decoding: enrollment 15-60 s with at least 10 s of speech, verification 3-60 s with at least 2 s of\nspeech, deepfake detection 0.5-120 s.\n\n**Stored audio.** Every file that was read successfully is kept privately for 30 days (for support and quality\nchecks), together with the result of its check, and then deleted. There is no opt-out: a request that sends\n`store_audio=false` is refused (`400 store_audio_not_supported`).\n\n**Retries.** Send an `Idempotency-Key` header (for example a new UUID) with every detection, enrollment and\nverification request, and send the same key again if you retry it. The retry returns the stored response\n(`idempotent_replay: true`, header `Idempotent-Replayed: true`) without running the check again or using\ncredits again. Keys are remembered for 24 h; results stay available for 30 days at\n`GET /v1/operations/{operation_id}`.\n\n**Errors.** Every non-2xx response uses the same envelope:\n`{\"error\": {\"type\", \"code\", \"message\", \"param\"}, \"request_id\"}`. Every response carries `X-Request-Id`.\n\n**Reading results.** `score` (0 to 1) says how likely a recording is AI-generated and `similarity` (-1 to 1)\nhow alike two voices are. Each result carries the `threshold` used for its decision. Results are strong\nsignals, not proof: try them on your own recordings before relying on them.","contact":{"name":"DetectifAI developer support","url":"https://platform.detectif.ai/docs"},"version":"1.0.0"},"servers":[{"url":"https://platform.detectif.ai","description":"Production"}],"paths":{"/v1/deepfake/detect":{"post":{"tags":["Deepfake detection"],"summary":"Detect AI-generated speech","description":"Checks whether a recording contains AI-generated speech. Send one audio file longer than 4 seconds and at most 120 seconds; at least 10 seconds of speech gives the most reliable verdicts. Use the result's `verdict`: always `real` or `fake`. `score` (0 to 1, higher means more likely AI-generated) is kept for older clients together with `label` and `is_synthetic`. Main failures: the file is not audio or is damaged (415/422), 4 seconds or shorter or longer than 120 seconds (422), not enough credits (402), the service is busy (503, retry later). Requires scope `deepfake:detect`.","operationId":"detectDeepfake","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128},{"type":"null"}],"description":"Optional (recommended) key that makes retries safe for 24 h: a retry with the same key and the same request returns the stored response without charging again.","examples":["9b1f6c1e-2c1a-4d6e-9a43-2f4f5b6f7a10"],"title":"Idempotency-Key"},"description":"Optional (recommended) key that makes retries safe for 24 h: a retry with the same key and the same request returns the stored response without charging again."}],"responses":{"200":{"description":"The check completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeepfakeResponse"},"examples":{"real":{"summary":"Real","value":{"request_id":"req_8f14e45fceea167a5a36dedd","operation_id":"op_6f1ed002ab5595859014ebf0951522d9","object":"deepfake.detection","model":{"name":"aletheia","version":"2026.10"},"latency_ms":58.3,"idempotent_replay":false,"result":{"score_semantics":"Higher means more likely AI-generated. Decide with the verdict, not the score alone.","verdict":"real","label":"genuine","is_synthetic":false,"score":0.0731,"duration_seconds":10.4,"scored_seconds":10.4,"segments":[{"start":0.0,"end":4.0,"score":0.061,"verdict":"real"},{"start":2.0,"end":6.0,"score":0.085,"verdict":"real"},{"start":4.0,"end":8.0,"score":0.07,"verdict":"real"},{"start":6.0,"end":10.0,"score":0.077,"verdict":"real"},{"start":6.4,"end":10.4,"score":0.072,"verdict":"real"}]},"credits":{"charged":50,"balance":4950}}},"fake":{"summary":"AI-generated","value":{"request_id":"req_8f14e45fceea167a5a36dedd","operation_id":"op_6f1ed002ab5595859014ebf0951522d9","object":"deepfake.detection","model":{"name":"aletheia","version":"2026.10"},"latency_ms":58.3,"idempotent_replay":false,"result":{"score_semantics":"Higher means more likely AI-generated. Decide with the verdict, not the score alone.","verdict":"fake","label":"synthetic","is_synthetic":true,"score":0.9827,"duration_seconds":10.0,"scored_seconds":10.0,"segments":[{"start":0.0,"end":4.0,"score":0.979,"verdict":"fake"},{"start":2.0,"end":6.0,"score":0.986,"verdict":"fake"},{"start":4.0,"end":8.0,"score":0.981,"verdict":"fake"},{"start":6.0,"end":10.0,"score":0.985,"verdict":"fake"}]},"credits":{"charged":50,"balance":4900}}}}}}},"400":{"description":"The request is invalid, for example a missing or malformed field.","content":{"application/json":{"example":{"error":{"type":"invalid_request","code":"invalid_speaker_id","message":"speaker_id must be 1-64 characters from A-Z, a-z, 0-9, '_', '.', ':' and '-'.","param":"speaker_id"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid or revoked.","content":{"application/json":{"example":{"error":{"type":"authentication","code":"invalid_api_key","message":"The API key is invalid."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits are available for this operation.","content":{"application/json":{"example":{"error":{"type":"insufficient_credits","code":"insufficient_credits","message":"Not enough credits are available for this operation."},"request_id":"req_8f14e45fceea167a5a36dedd","credits":{"available":20,"required":50}},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, the email address is not verified, or the account is suspended.","content":{"application/json":{"example":{"error":{"type":"permission","code":"insufficient_scope","message":"This API key is missing the required scope(s): deepfake:detect."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"The upload did not arrive in time (the whole file within 120 seconds, at least 64 KB per second).","content":{"application/json":{"example":{"error":{"type":"invalid_request","code":"upload_timeout","message":"The upload did not arrive in time: the whole request must be received within 120 s and at no less than 64 KB/s. Retry on a faster connection.","param":"file"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, for example a request with the same Idempotency-Key is still running, or the speaker already has the maximum number of samples.","content":{"application/json":{"example":{"error":{"type":"conflict","code":"operation_in_progress","message":"A request with this Idempotency-Key is still being processed; retry later or poll the operation."},"request_id":"req_8f14e45fceea167a5a36dedd","operation_id":"op_6f1ed002ab5595859014ebf0951522d9"},"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The upload is larger than 100 MB.","content":{"application/json":{"example":{"error":{"type":"payload_too_large","code":"file_too_large","message":"The upload exceeds the 100 MB limit.","param":"file"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Not a supported audio format, or the request is not multipart/form-data.","content":{"application/json":{"example":{"error":{"type":"unsupported_media","code":"unsupported_format","message":"Unsupported file format. Upload WAV, MP3, FLAC, OGG/Opus, WebM, M4A/AAC or AIFF audio.","param":"file"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The audio cannot be used (damaged, too short, too long, silent or too little speech; the message says what is needed), or the Idempotency-Key was already used for a different request.","content":{"application/json":{"example":{"error":{"type":"unprocessable_audio","code":"audio_too_short","message":"Audio must be longer than 4 seconds","param":"file"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or too many operations at the same time. Wait for the number of seconds in Retry-After.","content":{"application/json":{"example":{"error":{"type":"rate_limited","code":"rate_limited","message":"Model operation rate limit reached (30 per minute per account)."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something went wrong on our side. No credits were used.","content":{"application/json":{"example":{"error":{"type":"internal","code":"internal_error","message":"An internal error occurred."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The check failed on our side. No credits were used; retry later.","content":{"application/json":{"example":{"error":{"type":"internal","code":"inference_failed","message":"The check failed; no credits were used. Retry later."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service is busy, for example with many large uploads. Retry after the Retry-After seconds.","content":{"application/json":{"example":{"error":{"type":"overloaded","code":"server_busy","message":"Too many large uploads are in progress; retry shortly."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The check took too long. No credits were used; retry later.","content":{"application/json":{"example":{"error":{"type":"internal","code":"inference_timeout","message":"The check took too long; no credits were used. Retry later."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"description":"multipart/form-data with the audio in the `file` field.","content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"The audio file: WAV, MP3, FLAC, OGG/Opus, WebM, M4A/AAC or AIFF, at most 100 MB."}}},"encoding":{"file":{"contentType":"audio/*, application/octet-stream"}},"example":{"file":"call-2026-10-13.wav"}}}}}},"/v1/speakers/enroll":{"post":{"tags":["Speakers"],"summary":"Enroll a voice sample","description":"Saves a voice sample for a speaker so that later recordings can be verified against it. The speaker is created on first use. Send a recording of 15-60 seconds with at least 10 seconds of clear speech from that one person. Up to 5 samples per speaker; 2-3 samples from different sessions make verification more reliable. Main failures: too short, too long or too little speech (422, the message says what is needed), the speaker already has 5 samples (409), not enough credits (402). Requires scope `speakers:enroll`.","operationId":"enrollSpeaker","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128},{"type":"null"}],"description":"Optional (recommended) key that makes retries safe for 24 h: a retry with the same key and the same request returns the stored response without charging again.","examples":["9b1f6c1e-2c1a-4d6e-9a43-2f4f5b6f7a10"],"title":"Idempotency-Key"},"description":"Optional (recommended) key that makes retries safe for 24 h: a retry with the same key and the same request returns the stored response without charging again."}],"responses":{"200":{"description":"The sample was saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrollResponse"},"example":{"request_id":"req_8f14e45fceea167a5a36dedd","operation_id":"op_6f1ed002ab5595859014ebf0951522d9","object":"speaker.enrollment","speaker":{"speaker_id":"customer-4711","display_name":"Ada Lovelace","samples":1,"created_at":"2026-10-13T09:30:00Z","updated_at":"2026-10-13T09:30:00Z"},"quality":{"speech_seconds":17.9,"duration_seconds":19.2},"model":{"name":"eidos","version":"8e1b6c0a92f7"},"credits":{"charged":50,"balance":4900},"latency_ms":388.1,"idempotent_replay":false}}}},"400":{"description":"The request is invalid, for example a missing or malformed field.","content":{"application/json":{"example":{"error":{"type":"invalid_request","code":"invalid_speaker_id","message":"speaker_id must be 1-64 characters from A-Z, a-z, 0-9, '_', '.', ':' and '-'.","param":"speaker_id"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid or revoked.","content":{"application/json":{"example":{"error":{"type":"authentication","code":"invalid_api_key","message":"The API key is invalid."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits are available for this operation.","content":{"application/json":{"example":{"error":{"type":"insufficient_credits","code":"insufficient_credits","message":"Not enough credits are available for this operation."},"request_id":"req_8f14e45fceea167a5a36dedd","credits":{"available":20,"required":50}},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, the email address is not verified, or the account is suspended.","content":{"application/json":{"example":{"error":{"type":"permission","code":"insufficient_scope","message":"This API key is missing the required scope(s): deepfake:detect."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"The upload did not arrive in time (the whole file within 120 seconds, at least 64 KB per second).","content":{"application/json":{"example":{"error":{"type":"invalid_request","code":"upload_timeout","message":"The upload did not arrive in time: the whole request must be received within 120 s and at no less than 64 KB/s. Retry on a faster connection.","param":"file"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, for example a request with the same Idempotency-Key is still running, or the speaker already has the maximum number of samples.","content":{"application/json":{"example":{"error":{"type":"conflict","code":"too_many_samples","message":"This speaker already has the maximum of 5 samples.","param":"speaker_id"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The upload is larger than 100 MB.","content":{"application/json":{"example":{"error":{"type":"payload_too_large","code":"file_too_large","message":"The upload exceeds the 100 MB limit.","param":"file"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Not a supported audio format, or the request is not multipart/form-data.","content":{"application/json":{"example":{"error":{"type":"unsupported_media","code":"unsupported_format","message":"Unsupported file format. Upload WAV, MP3, FLAC, OGG/Opus, WebM, M4A/AAC or AIFF audio.","param":"file"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The audio cannot be used (damaged, too short, too long, silent or too little speech; the message says what is needed), or the Idempotency-Key was already used for a different request.","content":{"application/json":{"example":{"error":{"type":"unprocessable_audio","code":"audio_too_short","message":"Audio must be longer than 4 seconds","param":"file"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or too many operations at the same time. Wait for the number of seconds in Retry-After.","content":{"application/json":{"example":{"error":{"type":"rate_limited","code":"rate_limited","message":"Model operation rate limit reached (30 per minute per account)."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something went wrong on our side. No credits were used.","content":{"application/json":{"example":{"error":{"type":"internal","code":"internal_error","message":"An internal error occurred."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The check failed on our side. No credits were used; retry later.","content":{"application/json":{"example":{"error":{"type":"internal","code":"inference_failed","message":"The check failed; no credits were used. Retry later."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service is busy, for example with many large uploads. Retry after the Retry-After seconds.","content":{"application/json":{"example":{"error":{"type":"overloaded","code":"server_busy","message":"Too many large uploads are in progress; retry shortly."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The check took too long. No credits were used; retry later.","content":{"application/json":{"example":{"error":{"type":"internal","code":"inference_timeout","message":"The check took too long; no credits were used. Retry later."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"description":"multipart/form-data with the audio in the `file` field.","content":{"multipart/form-data":{"schema":{"type":"object","required":["file","speaker_id"],"properties":{"file":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"The audio file: WAV, MP3, FLAC, OGG/Opus, WebM, M4A/AAC or AIFF, at most 100 MB."},"speaker_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,64}$","minLength":1,"maxLength":64,"description":"Your identifier for the speaker (1-64 characters: letters, digits, _ . : -).","examples":["customer-4711"]},"display_name":{"type":"string","maxLength":128,"description":"Optional label for the speaker, shown in the dashboard.","examples":["Ada Lovelace"]}}},"encoding":{"file":{"contentType":"audio/*, application/octet-stream"}},"example":{"file":"ada-enrollment-1.wav","speaker_id":"customer-4711","display_name":"Ada Lovelace"}}}}}},"/v1/speakers/verify":{"post":{"tags":["Speakers"],"summary":"Verify a speaker","description":"Checks whether a recording is the voice of an enrolled speaker. Send a recording of 3-60 seconds with at least 2 seconds of speech. The result has a `decision` (`match` or `no_match`) and a `similarity` from -1 to 1 (higher means more alike). Main failures: unknown speaker (404), too short or too little speech (422), not enough credits (402). Requires scope `speakers:verify`.\n\nWith `detect_deepfake=true` the same recording is also checked for AI-generated speech (needs scope `deepfake:detect`; that check needs a recording longer than 4 seconds, otherwise only it fails). The two checks are counted separately, and only completed checks use credits:\n* if the synthetic-speech check fails, you still get the verification, with `deepfake.error`;\n* if the verification fails but the synthetic-speech check completed, you get the verification's error together with `partial` (the synthetic-speech result);\n* if both fail, you get the error and no credits are used.\n\nA retry with the same `Idempotency-Key` returns the same outcome again without running or counting the checks twice.","operationId":"verifySpeaker","security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string","minLength":1,"maxLength":128},{"type":"null"}],"description":"Optional (recommended) key that makes retries safe for 24 h: a retry with the same key and the same request returns the stored response without charging again.","examples":["9b1f6c1e-2c1a-4d6e-9a43-2f4f5b6f7a10"],"title":"Idempotency-Key"},"description":"Optional (recommended) key that makes retries safe for 24 h: a retry with the same key and the same request returns the stored response without charging again."}],"responses":{"200":{"description":"The check completed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyResponse"},"example":{"request_id":"req_8f14e45fceea167a5a36dedd","operation_id":"op_6f1ed002ab5595859014ebf0951522d9","object":"speaker.verification","speaker_id":"customer-4711","result":{"decision":"match","similarity":0.7412,"similarity_semantics":"Higher means the two voices are more alike. Not a percentage.","duration_seconds":4.1},"model":{"name":"eidos","version":"8e1b6c0a92f7"},"credits":{"charged":50,"balance":4850},"latency_ms":301.5,"idempotent_replay":false}}}},"400":{"description":"The request is invalid, for example a missing or malformed field.","content":{"application/json":{"example":{"error":{"type":"invalid_request","code":"invalid_speaker_id","message":"speaker_id must be 1-64 characters from A-Z, a-z, 0-9, '_', '.', ':' and '-'.","param":"speaker_id"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid or revoked.","content":{"application/json":{"example":{"error":{"type":"authentication","code":"invalid_api_key","message":"The API key is invalid."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits are available for this operation.","content":{"application/json":{"example":{"error":{"type":"insufficient_credits","code":"insufficient_credits","message":"Not enough credits are available for this operation."},"request_id":"req_8f14e45fceea167a5a36dedd","credits":{"available":20,"required":50}},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, the email address is not verified, or the account is suspended.","content":{"application/json":{"example":{"error":{"type":"permission","code":"insufficient_scope","message":"This API key is missing the required scope(s): deepfake:detect."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"The upload did not arrive in time (the whole file within 120 seconds, at least 64 KB per second).","content":{"application/json":{"example":{"error":{"type":"invalid_request","code":"upload_timeout","message":"The upload did not arrive in time: the whole request must be received within 120 s and at no less than 64 KB/s. Retry on a faster connection.","param":"file"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict, for example a request with the same Idempotency-Key is still running, or the speaker already has the maximum number of samples.","content":{"application/json":{"example":{"error":{"type":"conflict","code":"operation_in_progress","message":"A request with this Idempotency-Key is still being processed; retry later or poll the operation."},"request_id":"req_8f14e45fceea167a5a36dedd","operation_id":"op_6f1ed002ab5595859014ebf0951522d9"},"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The upload is larger than 100 MB.","content":{"application/json":{"example":{"error":{"type":"payload_too_large","code":"file_too_large","message":"The upload exceeds the 100 MB limit.","param":"file"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Not a supported audio format, or the request is not multipart/form-data.","content":{"application/json":{"example":{"error":{"type":"unsupported_media","code":"unsupported_format","message":"Unsupported file format. Upload WAV, MP3, FLAC, OGG/Opus, WebM, M4A/AAC or AIFF audio.","param":"file"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"The audio cannot be used (damaged, too short, too long, silent or too little speech; the message says what is needed), or the Idempotency-Key was already used for a different request.","content":{"application/json":{"example":{"error":{"type":"unprocessable_audio","code":"audio_too_short","message":"Audio must be longer than 4 seconds","param":"file"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or too many operations at the same time. Wait for the number of seconds in Retry-After.","content":{"application/json":{"example":{"error":{"type":"rate_limited","code":"rate_limited","message":"Model operation rate limit reached (30 per minute per account)."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something went wrong on our side. No credits were used.","content":{"application/json":{"example":{"error":{"type":"internal","code":"internal_error","message":"An internal error occurred."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The check failed on our side. No credits were used; retry later.","content":{"application/json":{"example":{"error":{"type":"internal","code":"inference_failed","message":"The check failed; no credits were used. Retry later."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"The service is busy, for example with many large uploads. Retry after the Retry-After seconds.","content":{"application/json":{"example":{"error":{"type":"overloaded","code":"inference_overloaded","message":"The service is at capacity; retry shortly."},"request_id":"req_8f14e45fceea167a5a36dedd","operation_id":"op_6f1ed002ab5595859014ebf0951522d9","partial":{"deepfake":{"verdict":"real","label":"genuine","is_synthetic":false,"score":0.08,"score_semantics":"Higher means more likely AI-generated. Decide with the verdict, not the score alone.","duration_seconds":6.1,"scored_seconds":6.1,"segments":[{"start":0.0,"end":4.0,"score":0.08,"verdict":"real"},{"start":2.0,"end":6.1,"score":0.07,"verdict":"real"}],"operation_id":"op_0b9d2f4c1e7a4b6c8d0e1f2a3b4c5d6e","credits_charged":50,"model":{"name":"aletheia","version":"2026.10"}},"credits":{"charged":50,"balance":4850}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The check took too long. No credits were used; retry later.","content":{"application/json":{"example":{"error":{"type":"internal","code":"inference_timeout","message":"The check took too long; no credits were used. Retry later."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found. Also returned for resources that belong to another account.","content":{"application/json":{"example":{"error":{"type":"not_found","code":"speaker_not_found","message":"No speaker with this speaker_id exists in your account.","param":"speaker_id"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"description":"multipart/form-data with the audio in the `file` field.","content":{"multipart/form-data":{"schema":{"type":"object","required":["file","speaker_id"],"properties":{"file":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"The audio file: WAV, MP3, FLAC, OGG/Opus, WebM, M4A/AAC or AIFF, at most 100 MB."},"speaker_id":{"type":"string","pattern":"^[A-Za-z0-9_.:-]{1,64}$","minLength":1,"maxLength":64,"description":"Your identifier for the speaker (1-64 characters: letters, digits, _ . : -).","examples":["customer-4711"]},"detect_deepfake":{"type":"boolean","default":false,"description":"Also check the same recording for AI-generated speech (needs scope deepfake:detect).","examples":[true]}}},"encoding":{"file":{"contentType":"audio/*, application/octet-stream"}},"example":{"file":"incoming-call.wav","speaker_id":"customer-4711","detect_deepfake":true}}}}}},"/v1/speakers":{"get":{"tags":["Speakers"],"summary":"List speakers","description":"Lists the speakers of your account, newest first, with how many voice samples each has. Use `limit` and `cursor` to page through long lists. Requires scope `speakers:read`.","operationId":"listSpeakers","security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"How many speakers to return (1-100).","examples":[20],"default":20,"title":"Limit"},"description":"How many speakers to return (1-100)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"description":"`next_cursor` from the previous page.","examples":["eyJ0IjoiMjAyNi0xMC0xMyJ9"],"title":"Cursor"},"description":"`next_cursor` from the previous page."}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpeakerList"},"example":{"request_id":"req_8f14e45fceea167a5a36dedd","object":"list","data":[{"speaker_id":"customer-4711","display_name":"Ada Lovelace","samples":2,"created_at":"2026-10-13T09:30:00Z","updated_at":"2026-10-13T09:41:12Z"}],"has_more":false}}}},"400":{"description":"The request is invalid, for example a missing or malformed field.","content":{"application/json":{"example":{"error":{"type":"invalid_request","code":"invalid_speaker_id","message":"speaker_id must be 1-64 characters from A-Z, a-z, 0-9, '_', '.', ':' and '-'.","param":"speaker_id"},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The API key is missing, invalid or revoked.","content":{"application/json":{"example":{"error":{"type":"authentication","code":"invalid_api_key","message":"The API key is invalid."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The key lacks the required scope, the email address is not verified, or the account is suspended.","content":{"application/json":{"example":{"error":{"type":"permission","code":"insufficient_scope","message":"This API key is missing the required scope(s): deepfake:detect."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests or too many operations at the same time. Wait for the number of seconds in Retry-After.","content":{"application/json":{"example":{"error":{"type":"rate_limited","code":"rate_limited","message":"Model operation rate limit reached (30 per minute per account)."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Something went wrong on our side. No credits were used.","content":{"application/json":{"example":{"error":{"type":"internal","code":"internal_error","message":"An internal error occurred."},"request_id":"req_8f14e45fceea167a5a36dedd"},"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/

# --- truncated at 32 KB (74 KB total) ---
# Full source: https://artifacts.apis.io/detectif-ai/openapi/_original/detectif-ai-api-openapi.json