Speech to Text API

오디오 파일 하나를 업로드하면 완성된 transcript를 JSON 또는 plain text로 반환합니다. multipart field와 응답은 OpenAI transcription API에서 익숙한 형태를 사용하지만 endpoint가 다르므로 OpenAI SDK의 Base URL만 바꾸는 방식은 지원하지 않습니다.

API 한눈에 보기

항목	값
Base URL	https://api.kitschlabs.com
Endpoint	POST /v1/speech-to-text
인증	Authorization: Bearer <API_KEY> 또는 xi-api-key: <API_KEY>
요청	multipart/form-data
모델	kitsch-stt-v1
최대 파일 크기	100 MiB
기본 응답	JSON

Speech to Text는 인증된 모든 계정에 기본 제공됩니다.

파일을 어떻게 변환하나요?

cURL

curl --request POST \
  "https://api.kitschlabs.com/v1/speech-to-text" \
  --header "Authorization: Bearer <API_KEY>" \
  --form "file=@speech.wav" \
  --form "model=kitsch-stt-v1" \
  --form "language=ko" \
  --form "response_format=json"

Python

import os

import requests

with open("speech.wav", "rb") as audio:
    response = requests.post(
        "https://api.kitschlabs.com/v1/speech-to-text",
        headers={"Authorization": f"Bearer {os.environ['KITSCH_API_KEY']}"},
        data={
            "model": "kitsch-stt-v1",
            "language": "ko",
            "response_format": "json",
        },
        files={"file": audio},
        timeout=120,
    )

response.raise_for_status()
print(response.json()["text"])

JavaScript

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("speech.wav")]), "speech.wav");
form.append("model", "kitsch-stt-v1");
form.append("language", "ko");
form.append("response_format", "json");

const response = await fetch("https://api.kitschlabs.com/v1/speech-to-text", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.KITSCH_API_KEY}` },
  body: form,
});

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

console.log((await response.json()).text);

어떤 필드를 보내나요?

필드	타입	필수	설명
file	file	예	변환할 오디오 파일. 최대 100 MiB
model	string	예	kitsch-stt-v1
language	string	아니요	예상 언어의 ISO 639-1 코드. 예: ko, en, ja
prompt	string	아니요	고유명사나 문맥을 알려 주는 짧은 힌트
response_format	string	아니요	json(기본값) 또는 text
stream	boolean	아니요	false만 지원
kitsch_options	JSON string	아니요	고급 인식 옵션

temperature, stream=true, 다른 모델 ID와 지원하지 않는 응답 형식은 오류로 거절됩니다. 파일을 실시간으로 전송하려면 Streaming API를 사용하세요.

고급 옵션

kitsch_options는 JSON 문자열로 보냅니다. 지원하는 key는 다음과 같습니다.

• language_hints, language_hints_strict
• enable_speaker_diarization
• enable_language_identification
• context
• translation

--form 'kitsch_options={"language_hints":["ko","en"],"enable_speaker_diarization":true}'

알 수 없는 key는 오류로 거절됩니다.

응답은 어떤 형태인가요?

response_format=json 응답:

{
  "text": "안녕하세요.",
  "usage": {
    "type": "duration",
    "seconds": 1.25
  }
}

response_format=text를 선택하면 UTF-8 plain text를 반환합니다. 지원 문의와 장애 추적에는 응답의 x-kitsch-request-id를 기록하세요.

과금은 어떻게 계산되나요?

성공한 요청의 입력 오디오 길이를 시작된 1초 단위로 올림하고 초당 0.1크레딧을 적용합니다. 예를 들어 4.2초와 5.0초는 각각 0.5크레딧, 5.1초는 0.6크레딧입니다. 실패하거나 입력 검증에서 거절된 요청은 차감하지 않습니다.

오류에는 어떻게 대응하나요?

오류 body는 error.message, error.type, error.param, error.code를 포함합니다.

{
  "error": {
    "message": "The uploaded file is too large.",
    "type": "invalid_request_error",
    "param": "file",
    "code": "file_too_large"
  }
}

상태 코드	의미	권장 행동
400·422	파일, 모델 또는 옵션 오류	요청 필드와 오디오 파일 확인
401	API 키가 없거나 유효하지 않음	인증 헤더 확인
402	사용 가능한 credit 부족	잔액과 청구 상태 확인
413	파일 크기 초과	100 MiB 이내로 줄여 재요청
429	요청 한도 또는 처리 용량 초과	Retry-After를 따르고 backoff 적용
503	일시적으로 처리할 수 없음	request ID를 기록하고 제한적으로 재시도