{"openapi":"3.1.0","info":{"title":"klangzeile Speech API","version":"1.0.0","description":"REST API for speech in German and English. POST /v1/tts turns text into MP3, WAV or OGG audio. POST /v1/transcriptions accepts an audio upload and processes it asynchronously into a transcript with optional speaker labels, summary, subtitles and translation. Transcripts are kept encrypted until you fetch them, for 24 h at most, and then deleted. AI agents can use the same API as tools through the MCP server at https://klangzeile.com/mcp (setup: https://klangzeile.com/docs/mcp).","termsOfService":"https://klangzeile.com/agb","contact":{"name":"klangzeile","url":"https://klangzeile.com/impressum"},"x-logo":{"url":"https://klangzeile.com/static/favicon/klangzeile-512.png","altText":"klangzeile logo"}},"paths":{"/v1/ping":{"get":{"tags":["Utility"],"summary":"Ping","description":"Authenticated no-op endpoint: verifies key + rate limit wiring.\nNot metered (no usage event) - products start metering in M2+.","operationId":"ping_v1_ping_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Ping V1 Ping Get"}}}}},"security":[{"bearerAuth":[]}]},"post":{"tags":["Utility"],"summary":"Ping Post","description":"POST variant so idempotency behaviour is testable end-to-end.","operationId":"ping_post_v1_ping_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Ping Post V1 Ping Post"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/voices":{"get":{"tags":["Text-to-speech"],"summary":"Voices","operationId":"voices_v1_voices_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Response Voices V1 Voices Get"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/v1/tts":{"post":{"tags":["Text-to-speech"],"summary":"Tts","operationId":"tts_v1_tts_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TtsRequest"}}},"required":true},"responses":{"200":{"description":"The audio in the requested `format`: mp3 (audio/mpeg), wav (audio/wav) or ogg (audio/ogg).","headers":{"X-Characters-Billed":{"description":"Characters billed (free allowance, then credit).","schema":{"type":"integer"}}},"content":{"audio/mpeg":{"schema":{"type":"string","format":"binary"}},"audio/wav":{"schema":{"type":"string","format":"binary"}},"audio/ogg":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Free allowance used up and not enough credit (CREDIT_EXHAUSTED).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Payload Too Large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Unprocessable Entity","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/transcriptions":{"post":{"tags":["Transcription"],"summary":"Create Transcription","operationId":"create_transcription_v1_transcriptions_post","requestBody":{"content":{"multipart/form-data":{"schema":{"properties":{"file":{"type":"string","format":"binary","description":"Audio (mp3, wav, m4a, ogg, webm, flac, aiff, amr, wma, caf); ≤ 200 MB, ≤ 3 h"},"language":{"type":"string","enum":["de","en","auto"],"default":"auto"},"summary":{"type":"boolean","description":"Structured summary by Mistral AI (EU, zero data retention)","default":true},"speakers":{"type":"boolean","description":"Speaker labels S1…Sn; rename them at delivery with speaker_names","default":false},"vocabulary":{"type":"string","description":"Comma-separated names/terms (≤ 100, ≤ 50 chars each, ≤ 2,000 characters in total; multi-word terms are split into single words and at most 100 words are sent) to improve spelling; merged with the account glossary (GET/PUT /v1/glossary), these terms first"},"timestamps":{"type":"string","enum":["segment","word"],"description":"word-level timestamps for subtitles; costs a second transcription pass on our side, never for you","default":"segment"},"translate":{"type":"string","enum":["de","en"],"description":"translate the transcript into this language (Mistral AI, EU, zero data retention); the summary is then written in that language"},"webhook_url":{"type":"string","format":"uri","description":"https URL notified with {id, status} when the job ends (unauthenticated)"}},"type":"object","required":["file"]}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Create Transcription V1 Transcriptions Post"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"402":{"description":"Free allowance used up and not enough credit (CREDIT_EXHAUSTED).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"411":{"description":"Length Required","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"413":{"description":"Payload Too Large","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"415":{"description":"Unsupported Media Type","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Unprocessable Entity","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/transcriptions/{job_id}":{"get":{"tags":["Transcription"],"summary":"Get Transcription","operationId":"get_transcription_v1_transcriptions__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"speaker_names","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Speaker Names"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","description":"Response body: JSON (default), or a subtitle file (srt or vtt) built from word or segment timestamps.","enum":["json","srt","vtt"],"default":"json","title":"Format"},"description":"Response body: JSON (default), or a subtitle file (srt or vtt) built from word or segment timestamps."},{"name":"lang","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Deliver the srt/vtt subtitles in this translated language instead of the original (must match a translation produced for this result); invalid together with format=json.","title":"Lang"},"description":"Deliver the srt/vtt subtitles in this translated language instead of the original (must match a translation produced for this result); invalid together with format=json."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"Gone","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Unprocessable Entity","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"tags":["Transcription"],"summary":"Delete Transcription","operationId":"delete_transcription_v1_transcriptions__job_id__delete","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"204":{"description":"Successful Response"},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/transcriptions/{job_id}/speakers":{"get":{"tags":["Transcription"],"summary":"Preview Speakers","description":"Who spoke, without consuming the one-shot result: enough to choose\nspeaker_names for the real GET.","operationId":"preview_speakers_v1_transcriptions__job_id__speakers_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Preview Speakers V1 Transcriptions  Job Id  Speakers Get"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Not Found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"409":{"description":"Conflict","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"410":{"description":"Gone","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/glossary":{"get":{"tags":["Glossary"],"summary":"Get Glossary","operationId":"get_glossary_v1_glossary_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Glossary V1 Glossary Get"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearerAuth":[]}]},"put":{"tags":["Glossary"],"summary":"Put Glossary","operationId":"put_glossary_v1_glossary_put","requestBody":{"content":{"application/json":{"schema":{"properties":{"terms":{"items":{"type":"string"},"type":"array","description":"≤ 100 terms, ≤ 50 characters each, ≤ 2,000 characters in total; an empty list deletes the glossary"}},"type":"object","required":["terms"]}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Put Glossary V1 Glossary Put"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"Unprocessable Entity","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"security":[{"bearerAuth":[]}]}},"/v1/credit":{"get":{"tags":["credit"],"summary":"Credit","operationId":"credit_v1_credit_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Credit V1 Credit Get"}}}},"401":{"description":"Unauthorized","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Too Many Requests","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"TtsRequest":{"properties":{"text":{"type":"string","title":"Text"},"voice":{"type":"string","title":"Voice","default":"de-thorsten"},"format":{"type":"string","enum":["mp3","wav","ogg"],"title":"Format","default":"mp3"},"speed":{"type":"number","maximum":2.0,"minimum":0.5,"title":"Speed","default":1.0}},"type":"object","required":["text"],"title":"TtsRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"Problem":{"type":"object","title":"Problem","required":["type","title","status","detail","instance","request_id","error_code"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"request_id":{"type":"string"},"error_code":{"type":"string","description":"Stable machine-readable code, e.g. UNAUTHORIZED, RATE_LIMITED"}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"servers":[{"url":"https://klangzeile.com"}],"externalDocs":{"description":"Quickstart","url":"https://klangzeile.com/quickstart"},"tags":[{"name":"Text-to-speech","description":"Voices and speech synthesis."},{"name":"Transcription","description":"Asynchronous speech-to-text jobs, subtitles and translation."},{"name":"Glossary","description":"Account-wide spellings used by transcriptions."},{"name":"credit","description":"Prepaid credit balance, free allowance left and current prices."},{"name":"Utility","description":"Check that an API key works."}]}