한국어 AI 내레이션 TTS API 개발가이드

요청과 응답

1작업 접수

POST/rest/tts/jobs

Bearer 인증
multipart/form-data
JSON 응답

요청 예제

curl --fail-with-body --request POST 'https://apick.app/rest/tts/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'voice_id=Kore' \
  --form-string 'style=따뜻하고 또렷하게' \
  --form-string 'text=오늘 기온은 5℃입니다.' \
  --form-string 'normalize_text=true'

curl --fail-with-body --request POST 'https://apick.app/rest/tts/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --form-string 'voice_id=Kore' \
  --form-string 'style=따뜻하고 또렷하게' \
  --form-string 'text=오늘 기온은 5℃입니다.' \
  --form-string 'normalize_text=true'

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

const form = new FormData();
form.append("voice_id", "Kore");
form.append("style", "따뜻하고 또렷하게");
form.append("text", "오늘 기온은 5℃입니다.");
form.append("normalize_text", "true");
const response = await fetch("https://apick.app/rest/tts/jobs", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

const form = new FormData();
form.append("voice_id", "Kore");
form.append("style", "따뜻하고 또렷하게");
form.append("text", "오늘 기온은 5℃입니다.");
form.append("normalize_text", "true");
const response = await fetch("https://apick.app/rest/tts/jobs", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

import os
import requests
parts = [
    ("voice_id", (None, "Kore")),
    ("style", (None, "따뜻하고 또렷하게")),
    ("text", (None, "오늘 기온은 5℃입니다.")),
    ("normalize_text", (None, "true")),
]
response = requests.request("POST", "https://apick.app/rest/tts/jobs",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

import os
import requests
parts = [
    ("voice_id", (None, "Kore")),
    ("style", (None, "따뜻하고 또렷하게")),
    ("text", (None, "오늘 기온은 5℃입니다.")),
    ("normalize_text", (None, "true")),
]
response = requests.request("POST", "https://apick.app/rest/tts/jobs",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'voice_id' => 'Kore',
    'style' => '따뜻하고 또렷하게',
    'text' => '오늘 기온은 5℃입니다.',
    'normalize_text' => 'true',
];
$curl = curl_init('https://apick.app/rest/tts/jobs');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'voice_id' => 'Kore',
    'style' => '따뜻하고 또렷하게',
    'text' => '오늘 기온은 5℃입니다.',
    'normalize_text' => 'true',
];
$curl = curl_init('https://apick.app/rest/tts/jobs');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

응답 예시

공개된 정적 응답 예제가 없는 경로입니다. 왼쪽 응답 필드에서 제공 범위를 확인하세요.

요청 파라미터 15개

파라미터

설명

textstring조건부

합성할 한국어 본문. text와 utterances 중 하나만 사용합니다. 정규화(normalize_text)를 쓰면 1~2,000자, 끄면 8,000자까지입니다(공백·줄바꿈 포함).

예시: 오늘 기온은 5℃입니다.

voice_idstring선택

사용할 목소리의 ID입니다. 목소리 목록에서 고른 값을 넣으며, 생략하면 엔진 기본 목소리로 합성됩니다. 목소리별로 억양·속도·성별이 다릅니다.

예시: Kore

stylestring선택

자유 서술 낭독 스타일 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

최대 길이: 1000자
예시: 따뜻하고 또렷하게

emotionstring선택

감정 표현. 생략 시 기본 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 12가지입니다. neutral = 감정을 넣지 않은 담담한 표현입니다. 안내·낭독의 기본값으로 쓰기 좋습니다. calm = 차분하고 낮은 감정입니다. 안정감이 필요한 안내에 적합합니다. cheerful = 밝고 경쾌한 감정입니다. 광고·환영 문구에 적합합니다. excited = 들뜨고 활기찬 감정입니다. 이벤트·강조 문장에 적합합니다. sad = 슬프고 가라앉은 감정입니다. 서사·추모 문구에 적합합니다. serious = 진지하고 단호한 감정입니다. 공지·경고 문구에 적합합니다. friendly = 친근하고 부드러운 감정입니다. 고객 응대에 적합합니다. empathetic = 공감하고 위로하는 감정입니다. 상담·안내에 적합합니다. confident = 확신에 찬 감정입니다. 발표·제안에 적합합니다. gentle = 조용하고 온화한 감정입니다. 수면·명상 콘텐츠에 적합합니다. whisper = 속삭이듯 작은 목소리입니다. ASMR·몰입형 콘텐츠에 적합합니다. narration = 낭독·해설에 맞춘 톤입니다. 문장 사이 쉼이 자연스럽습니다.

허용값: neutral calm cheerful excited sad serious friendly empathetic confident gentle whisper narration

tonestring선택

용도·톤. 생략 시 기본 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 9가지입니다. narration = 낭독·해설에 맞춘 톤입니다. 문장 사이 쉼이 자연스럽습니다. news = 뉴스 앵커처럼 또렷하고 일정한 톤입니다. audiobook = 오디오북 낭독 톤입니다. 긴 문장을 안정적으로 읽습니다. documentary = 다큐멘터리 해설 톤입니다. 차분하고 설명적입니다. ad = 광고 카피에 맞춘 톤입니다. 짧고 리듬감 있게 읽습니다. conversation = 대화하듯 자연스러운 톤입니다. announcement = 안내 방송 톤입니다. 또렷하고 전달력이 좋습니다. tutorial = 설명·강의 톤입니다. 단계 설명에 적합합니다. storytelling = 이야기 들려주는 톤입니다. 감정 변화를 살립니다.

허용값: narration news audiobook documentary ad conversation announcement tutorial storytelling

accentstring선택

억양. 생략 시 표준어 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 5가지입니다. standard = 지역색이 없는 표준어 억양입니다. seoul = 서울·수도권 억양입니다. gyeongsang = 경상도 억양입니다. jeolla = 전라도 억양입니다. chungcheong = 충청도 억양입니다.

허용값: standard seoul gyeongsang jeolla chungcheong

pacenumber선택

말 속도 배율 0.5~2.0. 1이 기본 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

pitchnumber선택

음높이 -12~12 반음. 0이 기본 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

volume_gain_dbnumber선택

음량 보정 -12~12 dB. 0이 기본 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

normalize_textboolean선택

기본 true true/false로 보내며, 생략하면 서버 기본값이 적용됩니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

예시: true

multi_speakerboolean선택

멀티화자. Gemini는 화자 2명까지 한 호출, ChatGPT는 발화별 목소리 대화 true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다.

speakersobject선택

화자 이름 → {voice_id, style, emotion, tone, accent, pace, pitch, volume_gain_db}

utterancesarray조건부

합성할 발화(문단) 목록입니다. 각 항목은 text·speaker·speed 등을 가지며, 전체 글자 수 제한을 함께 확인하세요.

utterances[0][text]string조건부

발화 본문. text와 utterances 중 하나만 사용합니다. 최대 100개 발화입니다. 본문 합계는 정규화(normalize_text)를 쓰면 2,000자, 끄면 8,000자까지입니다.

utterances[0][voice_id]string선택

이 발화에만 쓸 목소리 ID입니다. 생략하면 화자 설정, 그다음 최상위 voice_id를 씁니다.

응답 필드 9개

응답 필드

설명

dataobject

요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.

data.job_idstring

접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

data.statusstring

현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다. 이 경로에서는 항상 "waiting" 하나만 오는 고정값입니다.

허용값: waiting

data.voice_idstring

합성에 사용한 목소리 ID입니다. 요청의 voice_id를 그대로 반영하며, 생략한 경우 엔진 기본 목소리 ID가 옵니다.

data.character_countinteger

공백·문장부호를 포함한 합성 글자 수입니다. 이 값으로 과금 글자 수를 확인하며, 발화 목록을 쓰면 전체 발화의 합입니다.

apiobject

API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.

api.successboolean

API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.

api.costnumber

이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.

api.pl_idinteger

포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.

2작업 접수

POST/rest/tts/gemini/jobs

Bearer 인증
multipart/form-data
JSON 응답

요청 예제

printf '%s\r\n' '--apick-empty--' | curl --fail-with-body --request POST 'https://apick.app/rest/tts/gemini/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --header 'Content-Type: multipart/form-data; boundary=apick-empty' \
  --data-binary @-

printf '%s\r\n' '--apick-empty--' | curl --fail-with-body --request POST 'https://apick.app/rest/tts/gemini/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --header 'Content-Type: multipart/form-data; boundary=apick-empty' \
  --data-binary @-

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

const form = new FormData();
const response = await fetch("https://apick.app/rest/tts/gemini/jobs", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

const form = new FormData();
const response = await fetch("https://apick.app/rest/tts/gemini/jobs", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

import os
import requests
response = requests.request("POST", "https://apick.app/rest/tts/gemini/jobs",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"], "Content-Type": "multipart/form-data; boundary=apick-empty"},
    data=b"--apick-empty--\r\n",
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

import os
import requests
response = requests.request("POST", "https://apick.app/rest/tts/gemini/jobs",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"], "Content-Type": "multipart/form-data; boundary=apick-empty"},
    data=b"--apick-empty--\r\n",
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$headers[] = "Content-Type: multipart/form-data; boundary=apick-empty";
$form = "--apick-empty--\r\n";
$curl = curl_init('https://apick.app/rest/tts/gemini/jobs');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$headers[] = "Content-Type: multipart/form-data; boundary=apick-empty";
$form = "--apick-empty--\r\n";
$curl = curl_init('https://apick.app/rest/tts/gemini/jobs');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

응답 예시

공개된 정적 응답 예제가 없는 경로입니다. 왼쪽 응답 필드에서 제공 범위를 확인하세요.

요청 파라미터 15개

파라미터

설명

textstring조건부

합성할 한국어 본문. text와 utterances 중 하나만 사용합니다. 정규화(normalize_text)를 쓰면 1~2,000자, 끄면 8,000자까지입니다(공백·줄바꿈 포함).

voice_idstring선택

사용할 목소리의 ID입니다. 목소리 목록에서 고른 값을 넣으며, 생략하면 엔진 기본 목소리로 합성됩니다. 목소리별로 억양·속도·성별이 다릅니다.

stylestring선택

자유 서술 낭독 스타일 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

최대 길이: 1000자

emotionstring선택

허용값: neutral calm cheerful excited sad serious friendly empathetic confident gentle whisper narration

tonestring선택

허용값: narration news audiobook documentary ad conversation announcement tutorial storytelling

accentstring선택

허용값: standard seoul gyeongsang jeolla chungcheong

pacenumber선택

말 속도 배율 0.5~2.0. 1이 기본 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

pitchnumber선택

음높이 -12~12 반음. 0이 기본 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

volume_gain_dbnumber선택

음량 보정 -12~12 dB. 0이 기본 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

normalize_textboolean선택

multi_speakerboolean선택

speakersobject선택

화자 이름 → {voice_id, style, emotion, tone, accent, pace, pitch, volume_gain_db}

utterancesarray조건부

합성할 발화(문단) 목록입니다. 각 항목은 text·speaker·speed 등을 가지며, 전체 글자 수 제한을 함께 확인하세요.

utterances[0][text]string조건부

발화 본문. text와 utterances 중 하나만 사용합니다. 최대 100개 발화입니다. 본문 합계는 정규화(normalize_text)를 쓰면 2,000자, 끄면 8,000자까지입니다.

utterances[0][voice_id]string선택

이 발화에만 쓸 목소리 ID입니다. 생략하면 화자 설정, 그다음 최상위 voice_id를 씁니다.

응답 필드 9개

응답 필드

설명

dataobject

data.job_idstring

접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

data.statusstring

허용값: waiting

data.voice_idstring

합성에 사용한 목소리 ID입니다. 요청의 voice_id를 그대로 반영하며, 생략한 경우 엔진 기본 목소리 ID가 옵니다.

data.character_countinteger

공백·문장부호를 포함한 합성 글자 수입니다. 이 값으로 과금 글자 수를 확인하며, 발화 목록을 쓰면 전체 발화의 합입니다.

apiobject

api.successboolean

api.costnumber

api.pl_idinteger

3작업 접수

POST/rest/tts/openai/jobs

Bearer 인증
multipart/form-data
JSON 응답

요청 예제

printf '%s\r\n' '--apick-empty--' | curl --fail-with-body --request POST 'https://apick.app/rest/tts/openai/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --header 'Content-Type: multipart/form-data; boundary=apick-empty' \
  --data-binary @-

printf '%s\r\n' '--apick-empty--' | curl --fail-with-body --request POST 'https://apick.app/rest/tts/openai/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --header 'Content-Type: multipart/form-data; boundary=apick-empty' \
  --data-binary @-

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

const form = new FormData();
const response = await fetch("https://apick.app/rest/tts/openai/jobs", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

const form = new FormData();
const response = await fetch("https://apick.app/rest/tts/openai/jobs", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

import os
import requests
response = requests.request("POST", "https://apick.app/rest/tts/openai/jobs",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"], "Content-Type": "multipart/form-data; boundary=apick-empty"},
    data=b"--apick-empty--\r\n",
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

import os
import requests
response = requests.request("POST", "https://apick.app/rest/tts/openai/jobs",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"], "Content-Type": "multipart/form-data; boundary=apick-empty"},
    data=b"--apick-empty--\r\n",
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$headers[] = "Content-Type: multipart/form-data; boundary=apick-empty";
$form = "--apick-empty--\r\n";
$curl = curl_init('https://apick.app/rest/tts/openai/jobs');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$headers[] = "Content-Type: multipart/form-data; boundary=apick-empty";
$form = "--apick-empty--\r\n";
$curl = curl_init('https://apick.app/rest/tts/openai/jobs');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

응답 예시

공개된 정적 응답 예제가 없는 경로입니다. 왼쪽 응답 필드에서 제공 범위를 확인하세요.

요청 파라미터 15개

파라미터

설명

textstring조건부

합성할 한국어 본문. text와 utterances 중 하나만 사용합니다. 정규화(normalize_text)를 쓰면 1~2,000자, 끄면 8,000자까지입니다(공백·줄바꿈 포함).

voice_idstring선택

사용할 목소리의 ID입니다. 목소리 목록에서 고른 값을 넣으며, 생략하면 엔진 기본 목소리로 합성됩니다. 목소리별로 억양·속도·성별이 다릅니다.

stylestring선택

자유 서술 낭독 스타일 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

최대 길이: 1000자

emotionstring선택

허용값: neutral calm cheerful excited sad serious friendly empathetic confident gentle whisper narration

tonestring선택

허용값: narration news audiobook documentary ad conversation announcement tutorial storytelling

accentstring선택

허용값: standard seoul gyeongsang jeolla chungcheong

pacenumber선택

말 속도 배율 0.5~2.0. 1이 기본 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

pitchnumber선택

음높이 -12~12 반음. 0이 기본 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

volume_gain_dbnumber선택

음량 보정 -12~12 dB. 0이 기본 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

normalize_textboolean선택

multi_speakerboolean선택

speakersobject선택

화자 이름 → {voice_id, style, emotion, tone, accent, pace, pitch, volume_gain_db}

utterancesarray조건부

합성할 발화(문단) 목록입니다. 각 항목은 text·speaker·speed 등을 가지며, 전체 글자 수 제한을 함께 확인하세요.

utterances[0][text]string조건부

발화 본문. text와 utterances 중 하나만 사용합니다. 최대 100개 발화입니다. 본문 합계는 정규화(normalize_text)를 쓰면 2,000자, 끄면 8,000자까지입니다.

utterances[0][voice_id]string선택

이 발화에만 쓸 목소리 ID입니다. 생략하면 화자 설정, 그다음 최상위 voice_id를 씁니다.

응답 필드 9개

응답 필드

설명

dataobject

data.job_idstring

접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

data.statusstring

허용값: waiting

data.voice_idstring

합성에 사용한 목소리 ID입니다. 요청의 voice_id를 그대로 반영하며, 생략한 경우 엔진 기본 목소리 ID가 옵니다.

data.character_countinteger

공백·문장부호를 포함한 합성 글자 수입니다. 이 값으로 과금 글자 수를 확인하며, 발화 목록을 쓰면 전체 발화의 합입니다.

apiobject

api.successboolean

api.costnumber

api.pl_idinteger

4상태·목록 조회

GET/rest/tts/jobs/:job_id

Bearer 인증
요청 본문 없음
JSON 응답

경로의 job_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_JOB_ID 환경변수에서 읽습니다.

요청 예제

curl --fail-with-body --request GET "https://apick.app/rest/tts/jobs/${APICK_JOB_ID}" \
  --header "Authorization: Bearer $APICK_API_KEY"

# POSIX 셸과 jq가 필요합니다. APICK_JOB_ID에 접수 응답의 data.job_id를 설정하세요.
deadline=$(( $(date +%s) + 1200 )); delay=3
while [ "$(date +%s)" -lt "$deadline" ]; do
  result=$(curl --fail-with-body --request GET "https://apick.app/rest/tts/jobs/${APICK_JOB_ID}" \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 30) || exit 1
  state=$(printf '%s' "$result" | jq -r '.data.status')
  case "$state" in
    completed|completed_partial) printf '%s' "$result" | jq '.data'; exit 0 ;;
    waiting|processing) ;;
    *) printf '%s\n' "$result"; exit 1 ;;
  esac
  remaining=$(( deadline - $(date +%s) )); [ "$remaining" -gt 0 ] || break
  [ "$remaining" -ge "$delay" ] || delay=$remaining
  sleep "$delay"
  case "$delay" in 3) delay=5 ;; 5) delay=10 ;; *) delay=15 ;; esac
done
printf '%s\n' '클라이언트 대기시간 초과' >&2
exit 1

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}`, {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}`, {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

// 접수(POST)는 한 번만 보냅니다. APICK_JOB_ID에 접수 응답의 data.job_id를 설정하세요.
const controller = new AbortController(); // 사용자 취소 시 controller.abort()
const deadline = Date.now() + 1_200_000; // 클라이언트 권장 대기시간 20분
const delays = [3, 5, 10, 15]; let attempt = 0; let complete = false;
while (Date.now() < deadline && !controller.signal.aborted) {
  const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}`, {
    method: "GET",
    headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
    signal: AbortSignal.any([controller.signal, AbortSignal.timeout(Math.max(1, Math.min(30_000, deadline - Date.now())))]),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  const result = await response.json();
  if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
    throw new Error(JSON.stringify(result));
  }
  
  const data = result.data || {};
  if (["completed","completed_partial"].includes(data.status)) { console.log(data); complete = true; break; } // 이제 결과 다운로드 경로를 호출합니다.
  if (!["waiting","processing"].includes(data.status)) throw new Error(JSON.stringify(data)); // failed·cancelled 등은 멈춥니다.
  const remaining = deadline - Date.now(); if (remaining <= 0) break;
  const { setTimeout: wait } = await import("node:timers/promises");
  await wait(Math.min(delays[Math.min(attempt++, 3)] * 1000, remaining), undefined, { signal: controller.signal });
}
if (!complete) throw new Error("사용자 취소 또는 클라이언트 대기시간 초과");

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/tts/jobs/{job_id}".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/tts/jobs/{job_id}".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

# 접수(POST)는 한 번만 보냅니다. APICK_JOB_ID에 접수 응답의 data.job_id를 설정하세요. Ctrl+C로 취소할 수 있습니다.
import time
deadline = time.monotonic() + 1200  # 클라이언트 권장 대기시간 20분
delays = [3, 5, 10, 15]
attempt = 0
complete = False
while time.monotonic() < deadline:
    import os
    import requests
    from urllib.parse import quote
    response = requests.request("GET", "https://apick.app" + "/rest/tts/jobs/{job_id}".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
        headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
        timeout=(10, 30))
    response.raise_for_status()
    result = response.json()
    if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
        raise RuntimeError(result)
    
    data = result.get("data") or {}
    if data.get("status") in ["completed","completed_partial"]:
        print(data)  # 이제 결과 다운로드 경로를 호출합니다.
        complete = True
        break
    if data.get("status") not in ["waiting","processing"]:
        raise RuntimeError(data)  # failed·cancelled 등은 멈춥니다.
    remaining = deadline - time.monotonic()
    if remaining <= 0: break
    time.sleep(min(delays[min(attempt, 3)], remaining))
    attempt += 1
if not complete:
    raise TimeoutError("클라이언트 대기시간 초과")

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

<?php
// 접수(POST)는 한 번만 보냅니다. APICK_JOB_ID에 접수 응답의 data.job_id를 설정하세요.
$deadline = microtime(true) + 1200;
$delays = [3, 5, 10, 15]; $attempt = 0; $complete = false;
while (microtime(true) < $deadline) {
    $headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
    $curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '');
    curl_setopt_array($curl, [
        CURLOPT_CUSTOMREQUEST => 'GET',
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 30,
    ]);
    $body = curl_exec($curl);
    if ($body === false) { throw new RuntimeException(curl_error($curl)); }
    $status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    curl_close($curl);
    if ($status >= 400) { throw new RuntimeException($body); }
    $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
    if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
        throw new RuntimeException($body);
    }
    
    $data = $result["data"] ?? [];
    if (in_array($data["status"] ?? "", ["completed","completed_partial"], true)) { print_r($data); $complete = true; break; }
    if (!in_array($data["status"] ?? "", ["waiting","processing"], true)) { throw new RuntimeException($body); }
    $remaining = $deadline - microtime(true); if ($remaining <= 0) break;
    usleep((int)(min($delays[min($attempt++, 3)], $remaining) * 1000000));
}
if (!$complete) { throw new RuntimeException("클라이언트 대기시간 초과"); }

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

응답 예시

공개된 정적 응답 예제가 없는 경로입니다. 왼쪽 응답 필드에서 제공 범위를 확인하세요.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드 263개

응답 필드

설명

dataobject

data.job_idstring

접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

data.statusstring

현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다. 가능한 값은 5가지입니다. waiting = 접수만 되고 처리는 시작되지 않은 상태입니다. 결과가 비어 있으므로 같은 작업 ID로 잠시 후 다시 조회합니다. processing = 처리 중인 상태입니다. 결과가 아직 확정되지 않았으므로 완료 상태가 될 때까지 조회를 반복합니다. completed = 정상 완료된 상태입니다. 결과 필드나 파일 경로에서 실제 결과를 사용할 수 있습니다. cancelled = 작업이 취소된 상태입니다. 결과가 없으므로 필요하면 같은 조건으로 새로 접수해야 합니다. failed = 작업이 실패한 상태입니다. error의 code·message로 원인을 확인하고 재시도 가능 여부를 판단합니다.

허용값: waiting processing completed cancelled failed

data.result_availableboolean

결과 파일을 지금 내려받을 수 있는지 여부입니다. false면 아직 처리 중이거나 결과가 만료·삭제된 상태입니다. true = 결과 파일을 지금 내려받을 수 있는 경우, false = 처리 중이거나 실패·만료된 경우입니다.

data.subtitles_availableboolean

합성 결과의 자막 파일을 내려받을 수 있는지 여부입니다. false면 자막 생성이 생략되었거나 아직 준비되지 않은 상태입니다. true = 자막 파일을 내려받을 수 있는 경우, false = 자막 생성이 생략되었거나 아직 준비되지 않은 경우입니다.

data.resume_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.qualityobject

품질 상세. 아직 검사 전이면 null이거나 생략됩니다. 하위 필드에 코드·이름·상태 같은 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다. null 허용.

data.errorobject

작업 실패 원인을 담은 객체입니다. 공개 오류코드(code)와 사람이 읽을 설명(message)이 들어 있으며, 성공한 작업에는 없습니다.

apiobject

api.successboolean

api.costnumber

api.pl_idinteger

하위 필드 251개 더 보기

응답 필드

설명

data.quality.schema_versionstring

품질 결과 JSON의 규격 버전입니다. 필드 구성이 바뀔 때 증가하며, 클라이언트는 이 값을 기준으로 호환성을 판단할 수 있습니다.

data.quality.attemptinteger

현재 품질 검사가 몇 번째 시도인지 나타냅니다. 재검사할 때마다 증가하며, 후보별 attempt와 다를 수 있습니다.

data.quality.phasestring

작업이 현재 어느 처리 단계에 있는지 나타냅니다. waiting·processing·completed·failed 같은 값으로 진행 상태를 구분합니다. 가능한 값은 4가지입니다. waiting = 접수만 되고 처리는 시작되지 않은 상태입니다. 결과가 비어 있으므로 같은 작업 ID로 잠시 후 다시 조회합니다. processing = 처리 중인 상태입니다. 결과가 아직 확정되지 않았으므로 완료 상태가 될 때까지 조회를 반복합니다. completed = 정상 완료된 상태입니다. 결과 필드나 파일 경로에서 실제 결과를 사용할 수 있습니다. failed = 작업이 실패한 상태입니다. error의 code·message로 원인을 확인하고 재시도 가능 여부를 판단합니다.

data.quality.accepted_utterancesinteger

품질 검사를 통과한 발화 수입니다. 전체 발화 수와 비교해 실패·미검사 발화를 파악하세요.

data.quality.failed_utterancesinteger

품질 검사에서 실패한 발화 수입니다. 0이 아니면 실패 사유와 재시도 필요 여부를 함께 확인하세요.

data.quality.total_utterancesinteger

이 작업에 포함된 전체 발화 수입니다. accepted_utterances + failed_utterances와 같거나, 아직 검사 전인 발화가 있으면 더 클 수 있습니다.

data.quality.expires_atstring

후보 음원·검사 결과를 보관하는 만료 시각입니다. 이 시각이 지나면 후보 다운로드가 불가능할 수 있으며, 검사 전에는 null입니다. null 허용.

data.quality.queue_elapsed_secnumber

작업이 대기열에서 기다린 시간(초)입니다. 생성 시간과 분리해 지연 원인을 파악할 때 사용합니다.

data.quality.generation_elapsed_secnumber

실제 음성 생성에 걸린 시간(초)입니다. 대기 시간을 제외한 처리 시간입니다.

data.quality.utterancesarray

발화별 품질 검사 결과 목록입니다. 각 항목은 발화 ID·후보 ID·속도·반복·참조 검사 값을 포함합니다.

data.quality.utterances[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.utterances[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.utterances[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.utterances[].statusstring

이 항목의 처리·검사 상태입니다. waiting·processing·completed·failed 같은 값이 들어가며, 실패 사유는 reasons에서 확인하세요. 가능한 값은 4가지입니다. waiting = 접수만 되고 처리는 시작되지 않은 상태입니다. 결과가 비어 있으므로 같은 작업 ID로 잠시 후 다시 조회합니다. processing = 처리 중인 상태입니다. 결과가 아직 확정되지 않았으므로 완료 상태가 될 때까지 조회를 반복합니다. completed = 정상 완료된 상태입니다. 결과 필드나 파일 경로에서 실제 결과를 사용할 수 있습니다. failed = 작업이 실패한 상태입니다. error의 code·message로 원인을 확인하고 재시도 가능 여부를 판단합니다.

data.quality.utterances[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.utterances[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.utterances[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.utterances[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.utterances[].reasonsarray

검사·실패 사유 목록입니다. 통과·주의·실패 판정의 근거가 문장으로 들어가며, 사유가 없으면 빈 배열입니다. 가능한 값은 3가지입니다. 통과 = 기준을 충족해 그대로 쓸 수 있는 경우, 주의 = 경계값이라 결과는 쓰되 확인이 필요한 경우, 실패 = 기준을 충족하지 못해 쓰기 어려운 경우입니다.

data.quality.utterances[].speech_rateobject

발화 속도 검사. 검사 단계에 따라 일부 필드는 생략됩니다. 하위 필드에 코드·이름·상태 같은 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.

data.quality.utterances[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.utterances[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.utterances[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.utterances[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.utterances[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.utterances[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.utterances[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.utterances[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.utterances[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.utterances[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.utterances[].speech_rate.statusstring

속도 검사 결과입니다. 통과·주의·실패 같은 판정 값이 들어가며, 상세 사유는 같은 항목의 reasons를 확인하세요. 가능한 값은 3가지입니다. 통과 = 기준을 충족해 그대로 쓸 수 있는 경우, 주의 = 경계값이라 결과는 쓰되 확인이 필요한 경우, 실패 = 기준을 충족하지 못해 쓰기 어려운 경우입니다.

data.quality.utterances[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.utterances[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.utterances[].audio_availableboolean

이 후보의 음원을 다운로드할 수 있는지 여부입니다. false면 생성 실패·보관 만료 등으로 파일이 없습니다. true = 음원 파일을 내려받을 수 있는 경우, false = 생성 실패·보관 만료로 파일이 없는 경우입니다.

data.quality.utterances[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.utterances[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.utterances[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.utterances[].repeatobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다. 하위 필드에 코드·이름·상태 같은 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.

data.quality.utterances[].repeat.detectedboolean

반복·참조 음성 침입 같은 현상이 검출됐는지 여부입니다. true면 correlation·matched_characters 같은 근거 값을 함께 확인하세요. true = 반복·참조 음성 같은 현상이 검출된 경우, false = 검출되지 않은 경우입니다. true면 correlation·matched_characters 같은 근거 값을 함께 확인하세요.

data.quality.utterances[].repeat.suspectedboolean

검출이 확정되지는 않았지만 추가 확인이 필요한 상태인지 여부입니다. true면 detected와 별개로 수동 검토 대상입니다. true = 확정은 아니지만 추가 확인이 필요한 경우, false = 의심 정황이 없는 경우입니다.

data.quality.utterances[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.utterances[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.utterances[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.utterances[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.utterances[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.utterances[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.utterances[].reference_intrusionobject

data.quality.utterances[].reference_intrusion.detectedboolean

data.quality.utterances[].reference_intrusion.suspectedboolean

data.quality.utterances[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.utterances[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.utterances[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.utterances[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.utterances[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.utterances[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.utterances[].text_qa_statusstring

합성 텍스트와 인식 텍스트의 일치 검사 상태입니다. 통과·주의·실패 값이 들어가며, 상세 사유는 reasons를 확인하세요. 가능한 값은 3가지입니다. 통과 = 합성 텍스트와 인식 텍스트가 기준 이상으로 일치한 경우, 주의 = 일부 구간만 어긋나 확인이 필요한 경우, 실패 = 기준 미만으로 해당 음원을 쓰기 어려운 경우입니다. 주의·실패면 reasons의 사유를 함께 확인하세요.

data.quality.utterances[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.utterances[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.utterances[].tail_guard_attachedboolean

끝부분 잘림을 확인하기 위한 보호 구간이 음원에 붙었는지 여부입니다. 검사용으로만 쓰며 최종 음원에는 포함되지 않습니다. true = 끝부분 잘림을 확인하려고 검사용 보호 구간을 음원 끝에 붙인 상태인 경우, false = 보호 구간이 없는 최종 음원인 경우입니다. true인 음원은 검사 중간 결과이므로 그대로 배포하지 마세요.

data.quality.utterances[].tail_verifiedboolean

끝부분까지 정상적으로 생성됐는지 검증을 마쳤는지 여부입니다. false면 끝단 검사가 아직 끝나지 않았습니다. true = 음원 끝까지 정상 생성됐는지 검사를 마친 경우, false = 아직 검사 전이거나 끝단 확인에 실패한 경우입니다. false면 최종 음원으로 확정하지 말고 다시 조회하세요.

data.quality.utterances[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.utterances[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.utterances[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.utterances[].generation_budget_exhaustedboolean

이 발화의 자동 생성 시도 한도를 모두 사용했는지 여부입니다. true면 같은 조건으로는 더 이상 자동 재생성되지 않습니다. true = 허용된 재생성 횟수를 모두 사용해 더 시도할 수 없는 경우, false = 아직 재생성 여지가 남은 경우입니다. true면 새 작업으로 접수해야 합니다.

data.quality.utterances[].retry_requires_new_regeneration_keyboolean

재시도에 새 재생성 키가 필요한 상태인지 여부입니다. true면 기존 요청을 반복해도 새 후보가 생성되지 않습니다. true = 같은 재시도 키로는 다시 접수할 수 없어 새 키가 필요한 경우, false = 기존 키로 재시도할 수 있는 경우입니다. true면 새 재생성 키를 발급해 접수하세요.

data.quality.utterances[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.candidatesarray

음성 후보별 품질 검사 결과 목록입니다. 같은 발화의 여러 후보를 비교해 최종 후보를 고를 때 사용합니다.

data.quality.candidates[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.candidates[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.candidates[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.candidates[].statusstring

data.quality.candidates[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.candidates[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.candidates[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.candidates[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.candidates[].reasonsarray

data.quality.candidates[].speech_rateobject

data.quality.candidates[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.candidates[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.candidates[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.candidates[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.candidates[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.candidates[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.candidates[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.candidates[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.candidates[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.candidates[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.candidates[].speech_rate.statusstring

data.quality.candidates[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.candidates[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.candidates[].audio_availableboolean

data.quality.candidates[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.candidates[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.candidates[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.candidates[].repeatobject

data.quality.candidates[].repeat.detectedboolean

data.quality.candidates[].repeat.suspectedboolean

data.quality.candidates[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.candidates[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.candidates[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.candidates[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.candidates[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.candidates[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.candidates[].reference_intrusionobject

data.quality.candidates[].reference_intrusion.detectedboolean

data.quality.candidates[].reference_intrusion.suspectedboolean

data.quality.candidates[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.candidates[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.candidates[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.candidates[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.candidates[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.candidates[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.candidates[].text_qa_statusstring

data.quality.candidates[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.candidates[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.candidates[].tail_guard_attachedboolean

data.quality.candidates[].tail_verifiedboolean

data.quality.candidates[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.candidates[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.candidates[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.candidates[].generation_budget_exhaustedboolean

data.quality.candidates[].retry_requires_new_regeneration_keyboolean

data.quality.candidates[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.final_qualityobject

최종 선택된 음원의 품질 검사 결과입니다. 최종 검사 전에는 null이거나 생략됩니다.

data.quality.final_quality.schema_versionstring

품질 결과 JSON의 규격 버전입니다. 필드 구성이 바뀔 때 증가하며, 클라이언트는 이 값을 기준으로 호환성을 판단할 수 있습니다.

data.quality.final_quality.attemptinteger

현재 품질 검사가 몇 번째 시도인지 나타냅니다. 재검사할 때마다 증가하며, 후보별 attempt와 다를 수 있습니다.

data.quality.final_quality.phasestring

data.quality.final_quality.accepted_utterancesinteger

품질 검사를 통과한 발화 수입니다. 전체 발화 수와 비교해 실패·미검사 발화를 파악하세요.

data.quality.final_quality.failed_utterancesinteger

품질 검사에서 실패한 발화 수입니다. 0이 아니면 실패 사유와 재시도 필요 여부를 함께 확인하세요.

data.quality.final_quality.total_utterancesinteger

이 작업에 포함된 전체 발화 수입니다. accepted_utterances + failed_utterances와 같거나, 아직 검사 전인 발화가 있으면 더 클 수 있습니다.

data.quality.final_quality.expires_atstring

후보 음원·검사 결과를 보관하는 만료 시각입니다. 이 시각이 지나면 후보 다운로드가 불가능할 수 있으며, 검사 전에는 null입니다. null 허용.

data.quality.final_quality.queue_elapsed_secnumber

작업이 대기열에서 기다린 시간(초)입니다. 생성 시간과 분리해 지연 원인을 파악할 때 사용합니다.

data.quality.final_quality.generation_elapsed_secnumber

실제 음성 생성에 걸린 시간(초)입니다. 대기 시간을 제외한 처리 시간입니다.

data.quality.final_quality.utterancesarray

발화별 품질 검사 결과 목록입니다. 각 항목은 발화 ID·후보 ID·속도·반복·참조 검사 값을 포함합니다.

data.quality.final_quality.utterances[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.final_quality.utterances[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.final_quality.utterances[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.final_quality.utterances[].statusstring

data.quality.final_quality.utterances[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.final_quality.utterances[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.final_quality.utterances[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.final_quality.utterances[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.final_quality.utterances[].reasonsarray

data.quality.final_quality.utterances[].speech_rateobject

data.quality.final_quality.utterances[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.final_quality.utterances[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.final_quality.utterances[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.final_quality.utterances[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.utterances[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.final_quality.utterances[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.final_quality.utterances[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.utterances[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.final_quality.utterances[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.final_quality.utterances[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.final_quality.utterances[].speech_rate.statusstring

data.quality.final_quality.utterances[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.final_quality.utterances[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.final_quality.utterances[].audio_availableboolean

data.quality.final_quality.utterances[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.final_quality.utterances[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.final_quality.utterances[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.final_quality.utterances[].repeatobject

data.quality.final_quality.utterances[].repeat.detectedboolean

data.quality.final_quality.utterances[].repeat.suspectedboolean

data.quality.final_quality.utterances[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.utterances[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.utterances[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.utterances[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.utterances[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.utterances[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.utterances[].reference_intrusionobject

data.quality.final_quality.utterances[].reference_intrusion.detectedboolean

data.quality.final_quality.utterances[].reference_intrusion.suspectedboolean

data.quality.final_quality.utterances[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.utterances[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.utterances[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.utterances[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.utterances[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.utterances[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.utterances[].text_qa_statusstring

data.quality.final_quality.utterances[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.final_quality.utterances[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.final_quality.utterances[].tail_guard_attachedboolean

data.quality.final_quality.utterances[].tail_verifiedboolean

data.quality.final_quality.utterances[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.final_quality.utterances[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.final_quality.utterances[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.final_quality.utterances[].generation_budget_exhaustedboolean

data.quality.final_quality.utterances[].retry_requires_new_regeneration_keyboolean

data.quality.final_quality.utterances[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.final_quality.candidatesarray

음성 후보별 품질 검사 결과 목록입니다. 같은 발화의 여러 후보를 비교해 최종 후보를 고를 때 사용합니다.

data.quality.final_quality.candidates[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.final_quality.candidates[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.final_quality.candidates[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.final_quality.candidates[].statusstring

data.quality.final_quality.candidates[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.final_quality.candidates[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.final_quality.candidates[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.final_quality.candidates[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.final_quality.candidates[].reasonsarray

data.quality.final_quality.candidates[].speech_rateobject

data.quality.final_quality.candidates[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.final_quality.candidates[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.final_quality.candidates[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.final_quality.candidates[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.candidates[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.final_quality.candidates[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.final_quality.candidates[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.candidates[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.final_quality.candidates[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.final_quality.candidates[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.final_quality.candidates[].speech_rate.statusstring

data.quality.final_quality.candidates[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.final_quality.candidates[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.final_quality.candidates[].audio_availableboolean

data.quality.final_quality.candidates[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.final_quality.candidates[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.final_quality.candidates[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.final_quality.candidates[].repeatobject

data.quality.final_quality.candidates[].repeat.detectedboolean

data.quality.final_quality.candidates[].repeat.suspectedboolean

data.quality.final_quality.candidates[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.candidates[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.candidates[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.candidates[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.candidates[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.candidates[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.candidates[].reference_intrusionobject

data.quality.final_quality.candidates[].reference_intrusion.detectedboolean

data.quality.final_quality.candidates[].reference_intrusion.suspectedboolean

data.quality.final_quality.candidates[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.candidates[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.candidates[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.candidates[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.candidates[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.candidates[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.candidates[].text_qa_statusstring

data.quality.final_quality.candidates[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.final_quality.candidates[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.final_quality.candidates[].tail_guard_attachedboolean

data.quality.final_quality.candidates[].tail_verifiedboolean

data.quality.final_quality.candidates[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.final_quality.candidates[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.final_quality.candidates[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.final_quality.candidates[].generation_budget_exhaustedboolean

data.quality.final_quality.candidates[].retry_requires_new_regeneration_keyboolean

data.quality.final_quality.candidates[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.final_quality.statusstring

최종 선택된 음원의 검사 상태입니다. 통과·주의·실패 값을 확인해 다운로드 가능 여부를 판단하세요. 가능한 값은 3가지입니다. 통과 = 기준을 충족해 그대로 쓸 수 있는 경우, 주의 = 경계값이라 결과는 쓰되 확인이 필요한 경우, 실패 = 기준을 충족하지 못해 쓰기 어려운 경우입니다.

data.quality.final_quality.audio_sha256string

최종 선택된 음원의 SHA-256 해시입니다. 다운로드한 파일의 무결성을 확인할 때 사용합니다.

data.error.codestring

작업 실패의 공개 오류코드입니다. 같은 코드는 같은 원인을 뜻하며, 재시도 가능 여부는 오류 문서를 확인하세요.

data.error.messagestring

작업 실패 내용을 사람이 읽을 수 있게 설명합니다. 상세 원인은 서버 로그에만 남으며, 고객에게는 이 문구를 안내하세요.

5작업 취소

POST/rest/tts/jobs/:job_id/cancel

Bearer 인증
multipart/form-data
JSON 응답

경로의 job_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_JOB_ID 환경변수에서 읽습니다.

요청 예제

printf '%s\r\n' '--apick-empty--' | curl --fail-with-body --request POST "https://apick.app/rest/tts/jobs/${APICK_JOB_ID}/cancel" \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --header 'Content-Type: multipart/form-data; boundary=apick-empty' \
  --data-binary @-

printf '%s\r\n' '--apick-empty--' | curl --fail-with-body --request POST "https://apick.app/rest/tts/jobs/${APICK_JOB_ID}/cancel" \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --header 'Content-Type: multipart/form-data; boundary=apick-empty' \
  --data-binary @-

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

const form = new FormData();
const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/cancel`, {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

const form = new FormData();
const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/cancel`, {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

import os
import requests
from urllib.parse import quote
response = requests.request("POST", "https://apick.app" + "/rest/tts/jobs/{job_id}/cancel".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"], "Content-Type": "multipart/form-data; boundary=apick-empty"},
    data=b"--apick-empty--\r\n",
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

import os
import requests
from urllib.parse import quote
response = requests.request("POST", "https://apick.app" + "/rest/tts/jobs/{job_id}/cancel".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"], "Content-Type": "multipart/form-data; boundary=apick-empty"},
    data=b"--apick-empty--\r\n",
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$headers[] = "Content-Type: multipart/form-data; boundary=apick-empty";
$form = "--apick-empty--\r\n";
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/cancel');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$headers[] = "Content-Type: multipart/form-data; boundary=apick-empty";
$form = "--apick-empty--\r\n";
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/cancel');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

응답 예시

공개된 정적 응답 예제가 없는 경로입니다. 왼쪽 응답 필드에서 제공 범위를 확인하세요.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드 7개

응답 필드

설명

dataobject

data.job_idstring

접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

data.statusstring

현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다. 이 경로에서는 항상 "cancelled" 하나만 오는 고정값입니다.

허용값: cancelled

apiobject

api.successboolean

api.costnumber

api.pl_idinteger

6결과 받기

GET/rest/tts/jobs/:job_id/result

Bearer 인증
요청 본문 없음
파일 응답

경로의 job_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_JOB_ID 환경변수에서 읽습니다.

요청 예제

curl --fail-with-body --request GET "https://apick.app/rest/tts/jobs/${APICK_JOB_ID}/result" \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --dump-header response.headers --output result.mp3
# response.headers의 Content-Type을 확인한 뒤 파일을 사용하세요.

curl --fail-with-body --request GET "https://apick.app/rest/tts/jobs/${APICK_JOB_ID}/result" \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --dump-header response.headers --output result.mp3
# response.headers의 Content-Type을 확인한 뒤 파일을 사용하세요.

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/result`, {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
if ((response.headers.get("content-type") || "").includes("json")) {
  throw new Error(JSON.stringify(await response.json()));
}
const { writeFile } = await import("node:fs/promises");
await writeFile("result.mp3", new Uint8Array(await response.arrayBuffer()));

const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/result`, {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
if ((response.headers.get("content-type") || "").includes("json")) {
  throw new Error(JSON.stringify(await response.json()));
}
const { writeFile } = await import("node:fs/promises");
await writeFile("result.mp3", new Uint8Array(await response.arrayBuffer()));

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/tts/jobs/{job_id}/result".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120), stream=True)
response.raise_for_status()
if "json" in response.headers.get("Content-Type", ""):
    raise RuntimeError(response.json())
with open("result.mp3", "wb") as output:
    for chunk in response.iter_content(65536):
        output.write(chunk)

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/tts/jobs/{job_id}/result".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120), stream=True)
response.raise_for_status()
if "json" in response.headers.get("Content-Type", ""):
    raise RuntimeError(response.json())
with open("result.mp3", "wb") as output:
    for chunk in response.iter_content(65536):
        output.write(chunk)

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/result');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$type = curl_getinfo($curl, CURLINFO_CONTENT_TYPE) ?: "";
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
if (strpos($type, "json") !== false) { throw new RuntimeException($body); }
file_put_contents('result.mp3', $body);

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/result');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$type = curl_getinfo($curl, CURLINFO_CONTENT_TYPE) ?: "";
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
if (strpos($type, "json") !== false) { throw new RuntimeException($body); }
file_put_contents('result.mp3', $body);

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

응답200

파일 직접 응답 · audio/mpeg

정상 응답의 본문을 파일로 저장하세요. 실패하면 JSON 오류가 올 수 있으므로 HTTP 상태와 Content-Type을 먼저 확인하세요.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드 파일

정상 응답은 파일 본문입니다. 실패 시 JSON 오류가 올 수 있으므로 HTTP 상태와 Content-Type을 먼저 확인하세요.

7결과 받기

GET/rest/tts/jobs/:job_id/subtitles

Bearer 인증
요청 본문 없음
파일 응답

경로의 job_id는 앞 단계에서 받은 값으로 바꾸세요. 예제는 APICK_JOB_ID 환경변수에서 읽습니다.

요청 예제

curl --fail-with-body --request GET "https://apick.app/rest/tts/jobs/${APICK_JOB_ID}/subtitles" \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --dump-header response.headers --output result.bin
# response.headers의 Content-Type을 확인한 뒤 파일을 사용하세요.

curl --fail-with-body --request GET "https://apick.app/rest/tts/jobs/${APICK_JOB_ID}/subtitles" \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --dump-header response.headers --output result.bin
# response.headers의 Content-Type을 확인한 뒤 파일을 사용하세요.

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/subtitles`, {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
if ((response.headers.get("content-type") || "").includes("json")) {
  throw new Error(JSON.stringify(await response.json()));
}
const { writeFile } = await import("node:fs/promises");
await writeFile("result.bin", new Uint8Array(await response.arrayBuffer()));

const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/subtitles`, {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
if ((response.headers.get("content-type") || "").includes("json")) {
  throw new Error(JSON.stringify(await response.json()));
}
const { writeFile } = await import("node:fs/promises");
await writeFile("result.bin", new Uint8Array(await response.arrayBuffer()));

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/tts/jobs/{job_id}/subtitles".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120), stream=True)
response.raise_for_status()
if "json" in response.headers.get("Content-Type", ""):
    raise RuntimeError(response.json())
with open("result.bin", "wb") as output:
    for chunk in response.iter_content(65536):
        output.write(chunk)

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/tts/jobs/{job_id}/subtitles".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120), stream=True)
response.raise_for_status()
if "json" in response.headers.get("Content-Type", ""):
    raise RuntimeError(response.json())
with open("result.bin", "wb") as output:
    for chunk in response.iter_content(65536):
        output.write(chunk)

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/subtitles');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$type = curl_getinfo($curl, CURLINFO_CONTENT_TYPE) ?: "";
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
if (strpos($type, "json") !== false) { throw new RuntimeException($body); }
file_put_contents('result.bin', $body);

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/subtitles');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$type = curl_getinfo($curl, CURLINFO_CONTENT_TYPE) ?: "";
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
if (strpos($type, "json") !== false) { throw new RuntimeException($body); }
file_put_contents('result.bin', $body);

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

응답200

파일 직접 응답 · text/plain

정상 응답의 본문을 파일로 저장하세요. 실패하면 JSON 오류가 올 수 있으므로 HTTP 상태와 Content-Type을 먼저 확인하세요.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드 파일

정상 응답은 파일 본문입니다. 실패 시 JSON 오류가 올 수 있으므로 HTTP 상태와 Content-Type을 먼저 확인하세요.

8상태·목록 조회

GET/rest/tts/gemini/voices

Bearer 인증
요청 본문 없음
JSON 응답

요청 예제

curl --fail-with-body --request GET 'https://apick.app/rest/tts/gemini/voices' \
  --header "Authorization: Bearer $APICK_API_KEY"

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

const response = await fetch("https://apick.app/rest/tts/gemini/voices", {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

const response = await fetch("https://apick.app/rest/tts/gemini/voices", {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

import os
import requests
response = requests.request("GET", "https://apick.app/rest/tts/gemini/voices",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

import os
import requests
response = requests.request("GET", "https://apick.app/rest/tts/gemini/voices",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/gemini/voices');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/gemini/voices');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

응답 예시

공개된 정적 응답 예제가 없는 경로입니다. 왼쪽 응답 필드에서 제공 범위를 확인하세요.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드 263개

응답 필드

설명

dataobject

data.job_idstring

접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

data.statusstring

허용값: waiting processing completed cancelled failed

data.result_availableboolean

data.subtitles_availableboolean

data.resume_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.qualityobject

data.errorobject

작업 실패 원인을 담은 객체입니다. 공개 오류코드(code)와 사람이 읽을 설명(message)이 들어 있으며, 성공한 작업에는 없습니다.

apiobject

api.successboolean

api.costnumber

api.pl_idinteger

하위 필드 251개 더 보기

응답 필드

설명

data.quality.schema_versionstring

품질 결과 JSON의 규격 버전입니다. 필드 구성이 바뀔 때 증가하며, 클라이언트는 이 값을 기준으로 호환성을 판단할 수 있습니다.

data.quality.attemptinteger

현재 품질 검사가 몇 번째 시도인지 나타냅니다. 재검사할 때마다 증가하며, 후보별 attempt와 다를 수 있습니다.

data.quality.phasestring

data.quality.accepted_utterancesinteger

품질 검사를 통과한 발화 수입니다. 전체 발화 수와 비교해 실패·미검사 발화를 파악하세요.

data.quality.failed_utterancesinteger

품질 검사에서 실패한 발화 수입니다. 0이 아니면 실패 사유와 재시도 필요 여부를 함께 확인하세요.

data.quality.total_utterancesinteger

이 작업에 포함된 전체 발화 수입니다. accepted_utterances + failed_utterances와 같거나, 아직 검사 전인 발화가 있으면 더 클 수 있습니다.

data.quality.expires_atstring

후보 음원·검사 결과를 보관하는 만료 시각입니다. 이 시각이 지나면 후보 다운로드가 불가능할 수 있으며, 검사 전에는 null입니다. null 허용.

data.quality.queue_elapsed_secnumber

작업이 대기열에서 기다린 시간(초)입니다. 생성 시간과 분리해 지연 원인을 파악할 때 사용합니다.

data.quality.generation_elapsed_secnumber

실제 음성 생성에 걸린 시간(초)입니다. 대기 시간을 제외한 처리 시간입니다.

data.quality.utterancesarray

발화별 품질 검사 결과 목록입니다. 각 항목은 발화 ID·후보 ID·속도·반복·참조 검사 값을 포함합니다.

data.quality.utterances[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.utterances[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.utterances[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.utterances[].statusstring

data.quality.utterances[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.utterances[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.utterances[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.utterances[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.utterances[].reasonsarray

data.quality.utterances[].speech_rateobject

data.quality.utterances[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.utterances[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.utterances[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.utterances[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.utterances[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.utterances[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.utterances[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.utterances[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.utterances[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.utterances[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.utterances[].speech_rate.statusstring

data.quality.utterances[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.utterances[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.utterances[].audio_availableboolean

data.quality.utterances[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.utterances[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.utterances[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.utterances[].repeatobject

data.quality.utterances[].repeat.detectedboolean

data.quality.utterances[].repeat.suspectedboolean

data.quality.utterances[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.utterances[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.utterances[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.utterances[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.utterances[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.utterances[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.utterances[].reference_intrusionobject

data.quality.utterances[].reference_intrusion.detectedboolean

data.quality.utterances[].reference_intrusion.suspectedboolean

data.quality.utterances[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.utterances[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.utterances[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.utterances[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.utterances[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.utterances[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.utterances[].text_qa_statusstring

data.quality.utterances[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.utterances[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.utterances[].tail_guard_attachedboolean

data.quality.utterances[].tail_verifiedboolean

data.quality.utterances[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.utterances[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.utterances[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.utterances[].generation_budget_exhaustedboolean

data.quality.utterances[].retry_requires_new_regeneration_keyboolean

data.quality.utterances[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.candidatesarray

음성 후보별 품질 검사 결과 목록입니다. 같은 발화의 여러 후보를 비교해 최종 후보를 고를 때 사용합니다.

data.quality.candidates[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.candidates[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.candidates[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.candidates[].statusstring

data.quality.candidates[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.candidates[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.candidates[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.candidates[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.candidates[].reasonsarray

data.quality.candidates[].speech_rateobject

data.quality.candidates[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.candidates[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.candidates[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.candidates[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.candidates[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.candidates[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.candidates[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.candidates[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.candidates[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.candidates[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.candidates[].speech_rate.statusstring

data.quality.candidates[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.candidates[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.candidates[].audio_availableboolean

data.quality.candidates[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.candidates[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.candidates[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.candidates[].repeatobject

data.quality.candidates[].repeat.detectedboolean

data.quality.candidates[].repeat.suspectedboolean

data.quality.candidates[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.candidates[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.candidates[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.candidates[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.candidates[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.candidates[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.candidates[].reference_intrusionobject

data.quality.candidates[].reference_intrusion.detectedboolean

data.quality.candidates[].reference_intrusion.suspectedboolean

data.quality.candidates[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.candidates[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.candidates[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.candidates[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.candidates[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.candidates[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.candidates[].text_qa_statusstring

data.quality.candidates[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.candidates[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.candidates[].tail_guard_attachedboolean

data.quality.candidates[].tail_verifiedboolean

data.quality.candidates[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.candidates[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.candidates[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.candidates[].generation_budget_exhaustedboolean

data.quality.candidates[].retry_requires_new_regeneration_keyboolean

data.quality.candidates[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.final_qualityobject

최종 선택된 음원의 품질 검사 결과입니다. 최종 검사 전에는 null이거나 생략됩니다.

data.quality.final_quality.schema_versionstring

품질 결과 JSON의 규격 버전입니다. 필드 구성이 바뀔 때 증가하며, 클라이언트는 이 값을 기준으로 호환성을 판단할 수 있습니다.

data.quality.final_quality.attemptinteger

현재 품질 검사가 몇 번째 시도인지 나타냅니다. 재검사할 때마다 증가하며, 후보별 attempt와 다를 수 있습니다.

data.quality.final_quality.phasestring

data.quality.final_quality.accepted_utterancesinteger

품질 검사를 통과한 발화 수입니다. 전체 발화 수와 비교해 실패·미검사 발화를 파악하세요.

data.quality.final_quality.failed_utterancesinteger

품질 검사에서 실패한 발화 수입니다. 0이 아니면 실패 사유와 재시도 필요 여부를 함께 확인하세요.

data.quality.final_quality.total_utterancesinteger

이 작업에 포함된 전체 발화 수입니다. accepted_utterances + failed_utterances와 같거나, 아직 검사 전인 발화가 있으면 더 클 수 있습니다.

data.quality.final_quality.expires_atstring

후보 음원·검사 결과를 보관하는 만료 시각입니다. 이 시각이 지나면 후보 다운로드가 불가능할 수 있으며, 검사 전에는 null입니다. null 허용.

data.quality.final_quality.queue_elapsed_secnumber

작업이 대기열에서 기다린 시간(초)입니다. 생성 시간과 분리해 지연 원인을 파악할 때 사용합니다.

data.quality.final_quality.generation_elapsed_secnumber

실제 음성 생성에 걸린 시간(초)입니다. 대기 시간을 제외한 처리 시간입니다.

data.quality.final_quality.utterancesarray

발화별 품질 검사 결과 목록입니다. 각 항목은 발화 ID·후보 ID·속도·반복·참조 검사 값을 포함합니다.

data.quality.final_quality.utterances[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.final_quality.utterances[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.final_quality.utterances[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.final_quality.utterances[].statusstring

data.quality.final_quality.utterances[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.final_quality.utterances[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.final_quality.utterances[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.final_quality.utterances[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.final_quality.utterances[].reasonsarray

data.quality.final_quality.utterances[].speech_rateobject

data.quality.final_quality.utterances[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.final_quality.utterances[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.final_quality.utterances[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.final_quality.utterances[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.utterances[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.final_quality.utterances[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.final_quality.utterances[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.utterances[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.final_quality.utterances[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.final_quality.utterances[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.final_quality.utterances[].speech_rate.statusstring

data.quality.final_quality.utterances[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.final_quality.utterances[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.final_quality.utterances[].audio_availableboolean

data.quality.final_quality.utterances[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.final_quality.utterances[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.final_quality.utterances[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.final_quality.utterances[].repeatobject

data.quality.final_quality.utterances[].repeat.detectedboolean

data.quality.final_quality.utterances[].repeat.suspectedboolean

data.quality.final_quality.utterances[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.utterances[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.utterances[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.utterances[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.utterances[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.utterances[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.utterances[].reference_intrusionobject

data.quality.final_quality.utterances[].reference_intrusion.detectedboolean

data.quality.final_quality.utterances[].reference_intrusion.suspectedboolean

data.quality.final_quality.utterances[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.utterances[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.utterances[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.utterances[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.utterances[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.utterances[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.utterances[].text_qa_statusstring

data.quality.final_quality.utterances[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.final_quality.utterances[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.final_quality.utterances[].tail_guard_attachedboolean

data.quality.final_quality.utterances[].tail_verifiedboolean

data.quality.final_quality.utterances[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.final_quality.utterances[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.final_quality.utterances[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.final_quality.utterances[].generation_budget_exhaustedboolean

data.quality.final_quality.utterances[].retry_requires_new_regeneration_keyboolean

data.quality.final_quality.utterances[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.final_quality.candidatesarray

음성 후보별 품질 검사 결과 목록입니다. 같은 발화의 여러 후보를 비교해 최종 후보를 고를 때 사용합니다.

data.quality.final_quality.candidates[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.final_quality.candidates[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.final_quality.candidates[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.final_quality.candidates[].statusstring

data.quality.final_quality.candidates[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.final_quality.candidates[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.final_quality.candidates[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.final_quality.candidates[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.final_quality.candidates[].reasonsarray

data.quality.final_quality.candidates[].speech_rateobject

data.quality.final_quality.candidates[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.final_quality.candidates[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.final_quality.candidates[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.final_quality.candidates[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.candidates[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.final_quality.candidates[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.final_quality.candidates[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.candidates[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.final_quality.candidates[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.final_quality.candidates[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.final_quality.candidates[].speech_rate.statusstring

data.quality.final_quality.candidates[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.final_quality.candidates[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.final_quality.candidates[].audio_availableboolean

data.quality.final_quality.candidates[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.final_quality.candidates[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.final_quality.candidates[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.final_quality.candidates[].repeatobject

data.quality.final_quality.candidates[].repeat.detectedboolean

data.quality.final_quality.candidates[].repeat.suspectedboolean

data.quality.final_quality.candidates[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.candidates[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.candidates[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.candidates[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.candidates[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.candidates[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.candidates[].reference_intrusionobject

data.quality.final_quality.candidates[].reference_intrusion.detectedboolean

data.quality.final_quality.candidates[].reference_intrusion.suspectedboolean

data.quality.final_quality.candidates[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.candidates[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.candidates[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.candidates[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.candidates[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.candidates[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.candidates[].text_qa_statusstring

data.quality.final_quality.candidates[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.final_quality.candidates[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.final_quality.candidates[].tail_guard_attachedboolean

data.quality.final_quality.candidates[].tail_verifiedboolean

data.quality.final_quality.candidates[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.final_quality.candidates[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.final_quality.candidates[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.final_quality.candidates[].generation_budget_exhaustedboolean

data.quality.final_quality.candidates[].retry_requires_new_regeneration_keyboolean

data.quality.final_quality.candidates[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.final_quality.statusstring

data.quality.final_quality.audio_sha256string

최종 선택된 음원의 SHA-256 해시입니다. 다운로드한 파일의 무결성을 확인할 때 사용합니다.

data.error.codestring

작업 실패의 공개 오류코드입니다. 같은 코드는 같은 원인을 뜻하며, 재시도 가능 여부는 오류 문서를 확인하세요.

data.error.messagestring

작업 실패 내용을 사람이 읽을 수 있게 설명합니다. 상세 원인은 서버 로그에만 남으며, 고객에게는 이 문구를 안내하세요.

9상태·목록 조회

GET/rest/tts/openai/voices

Bearer 인증
요청 본문 없음
JSON 응답

요청 예제

curl --fail-with-body --request GET 'https://apick.app/rest/tts/openai/voices' \
  --header "Authorization: Bearer $APICK_API_KEY"

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

const response = await fetch("https://apick.app/rest/tts/openai/voices", {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

const response = await fetch("https://apick.app/rest/tts/openai/voices", {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

import os
import requests
response = requests.request("GET", "https://apick.app/rest/tts/openai/voices",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

import os
import requests
response = requests.request("GET", "https://apick.app/rest/tts/openai/voices",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/openai/voices');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/openai/voices');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

응답 예시

공개된 정적 응답 예제가 없는 경로입니다. 왼쪽 응답 필드에서 제공 범위를 확인하세요.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드 263개

응답 필드

설명

dataobject

data.job_idstring

접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

data.statusstring

허용값: waiting processing completed cancelled failed

data.result_availableboolean

data.subtitles_availableboolean

data.resume_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.qualityobject

data.errorobject

작업 실패 원인을 담은 객체입니다. 공개 오류코드(code)와 사람이 읽을 설명(message)이 들어 있으며, 성공한 작업에는 없습니다.

apiobject

api.successboolean

api.costnumber

api.pl_idinteger

하위 필드 251개 더 보기

응답 필드

설명

data.quality.schema_versionstring

품질 결과 JSON의 규격 버전입니다. 필드 구성이 바뀔 때 증가하며, 클라이언트는 이 값을 기준으로 호환성을 판단할 수 있습니다.

data.quality.attemptinteger

현재 품질 검사가 몇 번째 시도인지 나타냅니다. 재검사할 때마다 증가하며, 후보별 attempt와 다를 수 있습니다.

data.quality.phasestring

data.quality.accepted_utterancesinteger

품질 검사를 통과한 발화 수입니다. 전체 발화 수와 비교해 실패·미검사 발화를 파악하세요.

data.quality.failed_utterancesinteger

품질 검사에서 실패한 발화 수입니다. 0이 아니면 실패 사유와 재시도 필요 여부를 함께 확인하세요.

data.quality.total_utterancesinteger

이 작업에 포함된 전체 발화 수입니다. accepted_utterances + failed_utterances와 같거나, 아직 검사 전인 발화가 있으면 더 클 수 있습니다.

data.quality.expires_atstring

후보 음원·검사 결과를 보관하는 만료 시각입니다. 이 시각이 지나면 후보 다운로드가 불가능할 수 있으며, 검사 전에는 null입니다. null 허용.

data.quality.queue_elapsed_secnumber

작업이 대기열에서 기다린 시간(초)입니다. 생성 시간과 분리해 지연 원인을 파악할 때 사용합니다.

data.quality.generation_elapsed_secnumber

실제 음성 생성에 걸린 시간(초)입니다. 대기 시간을 제외한 처리 시간입니다.

data.quality.utterancesarray

발화별 품질 검사 결과 목록입니다. 각 항목은 발화 ID·후보 ID·속도·반복·참조 검사 값을 포함합니다.

data.quality.utterances[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.utterances[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.utterances[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.utterances[].statusstring

data.quality.utterances[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.utterances[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.utterances[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.utterances[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.utterances[].reasonsarray

data.quality.utterances[].speech_rateobject

data.quality.utterances[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.utterances[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.utterances[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.utterances[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.utterances[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.utterances[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.utterances[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.utterances[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.utterances[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.utterances[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.utterances[].speech_rate.statusstring

data.quality.utterances[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.utterances[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.utterances[].audio_availableboolean

data.quality.utterances[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.utterances[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.utterances[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.utterances[].repeatobject

data.quality.utterances[].repeat.detectedboolean

data.quality.utterances[].repeat.suspectedboolean

data.quality.utterances[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.utterances[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.utterances[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.utterances[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.utterances[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.utterances[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.utterances[].reference_intrusionobject

data.quality.utterances[].reference_intrusion.detectedboolean

data.quality.utterances[].reference_intrusion.suspectedboolean

data.quality.utterances[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.utterances[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.utterances[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.utterances[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.utterances[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.utterances[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.utterances[].text_qa_statusstring

data.quality.utterances[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.utterances[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.utterances[].tail_guard_attachedboolean

data.quality.utterances[].tail_verifiedboolean

data.quality.utterances[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.utterances[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.utterances[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.utterances[].generation_budget_exhaustedboolean

data.quality.utterances[].retry_requires_new_regeneration_keyboolean

data.quality.utterances[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.candidatesarray

음성 후보별 품질 검사 결과 목록입니다. 같은 발화의 여러 후보를 비교해 최종 후보를 고를 때 사용합니다.

data.quality.candidates[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.candidates[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.candidates[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.candidates[].statusstring

data.quality.candidates[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.candidates[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.candidates[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.candidates[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.candidates[].reasonsarray

data.quality.candidates[].speech_rateobject

data.quality.candidates[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.candidates[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.candidates[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.candidates[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.candidates[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.candidates[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.candidates[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.candidates[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.candidates[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.candidates[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.candidates[].speech_rate.statusstring

data.quality.candidates[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.candidates[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.candidates[].audio_availableboolean

data.quality.candidates[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.candidates[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.candidates[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.candidates[].repeatobject

data.quality.candidates[].repeat.detectedboolean

data.quality.candidates[].repeat.suspectedboolean

data.quality.candidates[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.candidates[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.candidates[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.candidates[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.candidates[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.candidates[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.candidates[].reference_intrusionobject

data.quality.candidates[].reference_intrusion.detectedboolean

data.quality.candidates[].reference_intrusion.suspectedboolean

data.quality.candidates[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.candidates[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.candidates[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.candidates[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.candidates[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.candidates[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.candidates[].text_qa_statusstring

data.quality.candidates[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.candidates[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.candidates[].tail_guard_attachedboolean

data.quality.candidates[].tail_verifiedboolean

data.quality.candidates[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.candidates[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.candidates[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.candidates[].generation_budget_exhaustedboolean

data.quality.candidates[].retry_requires_new_regeneration_keyboolean

data.quality.candidates[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.final_qualityobject

최종 선택된 음원의 품질 검사 결과입니다. 최종 검사 전에는 null이거나 생략됩니다.

data.quality.final_quality.schema_versionstring

품질 결과 JSON의 규격 버전입니다. 필드 구성이 바뀔 때 증가하며, 클라이언트는 이 값을 기준으로 호환성을 판단할 수 있습니다.

data.quality.final_quality.attemptinteger

현재 품질 검사가 몇 번째 시도인지 나타냅니다. 재검사할 때마다 증가하며, 후보별 attempt와 다를 수 있습니다.

data.quality.final_quality.phasestring

data.quality.final_quality.accepted_utterancesinteger

품질 검사를 통과한 발화 수입니다. 전체 발화 수와 비교해 실패·미검사 발화를 파악하세요.

data.quality.final_quality.failed_utterancesinteger

품질 검사에서 실패한 발화 수입니다. 0이 아니면 실패 사유와 재시도 필요 여부를 함께 확인하세요.

data.quality.final_quality.total_utterancesinteger

이 작업에 포함된 전체 발화 수입니다. accepted_utterances + failed_utterances와 같거나, 아직 검사 전인 발화가 있으면 더 클 수 있습니다.

data.quality.final_quality.expires_atstring

후보 음원·검사 결과를 보관하는 만료 시각입니다. 이 시각이 지나면 후보 다운로드가 불가능할 수 있으며, 검사 전에는 null입니다. null 허용.

data.quality.final_quality.queue_elapsed_secnumber

작업이 대기열에서 기다린 시간(초)입니다. 생성 시간과 분리해 지연 원인을 파악할 때 사용합니다.

data.quality.final_quality.generation_elapsed_secnumber

실제 음성 생성에 걸린 시간(초)입니다. 대기 시간을 제외한 처리 시간입니다.

data.quality.final_quality.utterancesarray

발화별 품질 검사 결과 목록입니다. 각 항목은 발화 ID·후보 ID·속도·반복·참조 검사 값을 포함합니다.

data.quality.final_quality.utterances[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.final_quality.utterances[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.final_quality.utterances[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.final_quality.utterances[].statusstring

data.quality.final_quality.utterances[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.final_quality.utterances[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.final_quality.utterances[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.final_quality.utterances[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.final_quality.utterances[].reasonsarray

data.quality.final_quality.utterances[].speech_rateobject

data.quality.final_quality.utterances[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.final_quality.utterances[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.final_quality.utterances[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.final_quality.utterances[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.utterances[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.final_quality.utterances[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.final_quality.utterances[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.utterances[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.final_quality.utterances[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.final_quality.utterances[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.final_quality.utterances[].speech_rate.statusstring

data.quality.final_quality.utterances[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.final_quality.utterances[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.final_quality.utterances[].audio_availableboolean

data.quality.final_quality.utterances[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.final_quality.utterances[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.final_quality.utterances[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.final_quality.utterances[].repeatobject

data.quality.final_quality.utterances[].repeat.detectedboolean

data.quality.final_quality.utterances[].repeat.suspectedboolean

data.quality.final_quality.utterances[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.utterances[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.utterances[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.utterances[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.utterances[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.utterances[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.utterances[].reference_intrusionobject

data.quality.final_quality.utterances[].reference_intrusion.detectedboolean

data.quality.final_quality.utterances[].reference_intrusion.suspectedboolean

data.quality.final_quality.utterances[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.utterances[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.utterances[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.utterances[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.utterances[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.utterances[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.utterances[].text_qa_statusstring

data.quality.final_quality.utterances[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.final_quality.utterances[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.final_quality.utterances[].tail_guard_attachedboolean

data.quality.final_quality.utterances[].tail_verifiedboolean

data.quality.final_quality.utterances[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.final_quality.utterances[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.final_quality.utterances[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.final_quality.utterances[].generation_budget_exhaustedboolean

data.quality.final_quality.utterances[].retry_requires_new_regeneration_keyboolean

data.quality.final_quality.utterances[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.final_quality.candidatesarray

음성 후보별 품질 검사 결과 목록입니다. 같은 발화의 여러 후보를 비교해 최종 후보를 고를 때 사용합니다.

data.quality.final_quality.candidates[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.final_quality.candidates[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.final_quality.candidates[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.final_quality.candidates[].statusstring

data.quality.final_quality.candidates[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.final_quality.candidates[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.final_quality.candidates[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.final_quality.candidates[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.final_quality.candidates[].reasonsarray

data.quality.final_quality.candidates[].speech_rateobject

data.quality.final_quality.candidates[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.final_quality.candidates[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.final_quality.candidates[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.final_quality.candidates[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.candidates[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.final_quality.candidates[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.final_quality.candidates[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.candidates[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.final_quality.candidates[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.final_quality.candidates[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.final_quality.candidates[].speech_rate.statusstring

data.quality.final_quality.candidates[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.final_quality.candidates[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.final_quality.candidates[].audio_availableboolean

data.quality.final_quality.candidates[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.final_quality.candidates[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.final_quality.candidates[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.final_quality.candidates[].repeatobject

data.quality.final_quality.candidates[].repeat.detectedboolean

data.quality.final_quality.candidates[].repeat.suspectedboolean

data.quality.final_quality.candidates[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.candidates[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.candidates[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.candidates[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.candidates[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.candidates[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.candidates[].reference_intrusionobject

data.quality.final_quality.candidates[].reference_intrusion.detectedboolean

data.quality.final_quality.candidates[].reference_intrusion.suspectedboolean

data.quality.final_quality.candidates[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.candidates[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.candidates[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.candidates[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.candidates[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.candidates[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.candidates[].text_qa_statusstring

data.quality.final_quality.candidates[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.final_quality.candidates[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.final_quality.candidates[].tail_guard_attachedboolean

data.quality.final_quality.candidates[].tail_verifiedboolean

data.quality.final_quality.candidates[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.final_quality.candidates[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.final_quality.candidates[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.final_quality.candidates[].generation_budget_exhaustedboolean

data.quality.final_quality.candidates[].retry_requires_new_regeneration_keyboolean

data.quality.final_quality.candidates[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.final_quality.statusstring

data.quality.final_quality.audio_sha256string

최종 선택된 음원의 SHA-256 해시입니다. 다운로드한 파일의 무결성을 확인할 때 사용합니다.

data.error.codestring

작업 실패의 공개 오류코드입니다. 같은 코드는 같은 원인을 뜻하며, 재시도 가능 여부는 오류 문서를 확인하세요.

data.error.messagestring

작업 실패 내용을 사람이 읽을 수 있게 설명합니다. 상세 원인은 서버 로그에만 남으며, 고객에게는 이 문구를 안내하세요.

10상태·목록 조회

GET/rest/tts/options

Bearer 인증
요청 본문 없음
JSON 응답

요청 예제

curl --fail-with-body --request GET 'https://apick.app/rest/tts/options' \
  --header "Authorization: Bearer $APICK_API_KEY"

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

const response = await fetch("https://apick.app/rest/tts/options", {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

const response = await fetch("https://apick.app/rest/tts/options", {
  method: "GET",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

import os
import requests
response = requests.request("GET", "https://apick.app/rest/tts/options",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

import os
import requests
response = requests.request("GET", "https://apick.app/rest/tts/options",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/options');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/options');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

응답 예시

공개된 정적 응답 예제가 없는 경로입니다. 왼쪽 응답 필드에서 제공 범위를 확인하세요.

요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드 263개

응답 필드

설명

dataobject

data.job_idstring

접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

data.statusstring

허용값: waiting processing completed cancelled failed

data.result_availableboolean

data.subtitles_availableboolean

data.resume_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.qualityobject

data.errorobject

작업 실패 원인을 담은 객체입니다. 공개 오류코드(code)와 사람이 읽을 설명(message)이 들어 있으며, 성공한 작업에는 없습니다.

apiobject

api.successboolean

api.costnumber

api.pl_idinteger

하위 필드 251개 더 보기

응답 필드

설명

data.quality.schema_versionstring

품질 결과 JSON의 규격 버전입니다. 필드 구성이 바뀔 때 증가하며, 클라이언트는 이 값을 기준으로 호환성을 판단할 수 있습니다.

data.quality.attemptinteger

현재 품질 검사가 몇 번째 시도인지 나타냅니다. 재검사할 때마다 증가하며, 후보별 attempt와 다를 수 있습니다.

data.quality.phasestring

data.quality.accepted_utterancesinteger

품질 검사를 통과한 발화 수입니다. 전체 발화 수와 비교해 실패·미검사 발화를 파악하세요.

data.quality.failed_utterancesinteger

품질 검사에서 실패한 발화 수입니다. 0이 아니면 실패 사유와 재시도 필요 여부를 함께 확인하세요.

data.quality.total_utterancesinteger

이 작업에 포함된 전체 발화 수입니다. accepted_utterances + failed_utterances와 같거나, 아직 검사 전인 발화가 있으면 더 클 수 있습니다.

data.quality.expires_atstring

후보 음원·검사 결과를 보관하는 만료 시각입니다. 이 시각이 지나면 후보 다운로드가 불가능할 수 있으며, 검사 전에는 null입니다. null 허용.

data.quality.queue_elapsed_secnumber

작업이 대기열에서 기다린 시간(초)입니다. 생성 시간과 분리해 지연 원인을 파악할 때 사용합니다.

data.quality.generation_elapsed_secnumber

실제 음성 생성에 걸린 시간(초)입니다. 대기 시간을 제외한 처리 시간입니다.

data.quality.utterancesarray

발화별 품질 검사 결과 목록입니다. 각 항목은 발화 ID·후보 ID·속도·반복·참조 검사 값을 포함합니다.

data.quality.utterances[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.utterances[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.utterances[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.utterances[].statusstring

data.quality.utterances[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.utterances[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.utterances[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.utterances[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.utterances[].reasonsarray

data.quality.utterances[].speech_rateobject

data.quality.utterances[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.utterances[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.utterances[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.utterances[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.utterances[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.utterances[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.utterances[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.utterances[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.utterances[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.utterances[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.utterances[].speech_rate.statusstring

data.quality.utterances[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.utterances[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.utterances[].audio_availableboolean

data.quality.utterances[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.utterances[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.utterances[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.utterances[].repeatobject

data.quality.utterances[].repeat.detectedboolean

data.quality.utterances[].repeat.suspectedboolean

data.quality.utterances[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.utterances[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.utterances[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.utterances[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.utterances[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.utterances[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.utterances[].reference_intrusionobject

data.quality.utterances[].reference_intrusion.detectedboolean

data.quality.utterances[].reference_intrusion.suspectedboolean

data.quality.utterances[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.utterances[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.utterances[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.utterances[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.utterances[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.utterances[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.utterances[].text_qa_statusstring

data.quality.utterances[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.utterances[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.utterances[].tail_guard_attachedboolean

data.quality.utterances[].tail_verifiedboolean

data.quality.utterances[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.utterances[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.utterances[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.utterances[].generation_budget_exhaustedboolean

data.quality.utterances[].retry_requires_new_regeneration_keyboolean

data.quality.utterances[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.candidatesarray

음성 후보별 품질 검사 결과 목록입니다. 같은 발화의 여러 후보를 비교해 최종 후보를 고를 때 사용합니다.

data.quality.candidates[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.candidates[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.candidates[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.candidates[].statusstring

data.quality.candidates[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.candidates[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.candidates[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.candidates[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.candidates[].reasonsarray

data.quality.candidates[].speech_rateobject

data.quality.candidates[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.candidates[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.candidates[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.candidates[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.candidates[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.candidates[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.candidates[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.candidates[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.candidates[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.candidates[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.candidates[].speech_rate.statusstring

data.quality.candidates[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.candidates[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.candidates[].audio_availableboolean

data.quality.candidates[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.candidates[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.candidates[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.candidates[].repeatobject

data.quality.candidates[].repeat.detectedboolean

data.quality.candidates[].repeat.suspectedboolean

data.quality.candidates[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.candidates[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.candidates[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.candidates[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.candidates[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.candidates[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.candidates[].reference_intrusionobject

data.quality.candidates[].reference_intrusion.detectedboolean

data.quality.candidates[].reference_intrusion.suspectedboolean

data.quality.candidates[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.candidates[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.candidates[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.candidates[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.candidates[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.candidates[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.candidates[].text_qa_statusstring

data.quality.candidates[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.candidates[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.candidates[].tail_guard_attachedboolean

data.quality.candidates[].tail_verifiedboolean

data.quality.candidates[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.candidates[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.candidates[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.candidates[].generation_budget_exhaustedboolean

data.quality.candidates[].retry_requires_new_regeneration_keyboolean

data.quality.candidates[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.final_qualityobject

최종 선택된 음원의 품질 검사 결과입니다. 최종 검사 전에는 null이거나 생략됩니다.

data.quality.final_quality.schema_versionstring

품질 결과 JSON의 규격 버전입니다. 필드 구성이 바뀔 때 증가하며, 클라이언트는 이 값을 기준으로 호환성을 판단할 수 있습니다.

data.quality.final_quality.attemptinteger

현재 품질 검사가 몇 번째 시도인지 나타냅니다. 재검사할 때마다 증가하며, 후보별 attempt와 다를 수 있습니다.

data.quality.final_quality.phasestring

data.quality.final_quality.accepted_utterancesinteger

품질 검사를 통과한 발화 수입니다. 전체 발화 수와 비교해 실패·미검사 발화를 파악하세요.

data.quality.final_quality.failed_utterancesinteger

품질 검사에서 실패한 발화 수입니다. 0이 아니면 실패 사유와 재시도 필요 여부를 함께 확인하세요.

data.quality.final_quality.total_utterancesinteger

이 작업에 포함된 전체 발화 수입니다. accepted_utterances + failed_utterances와 같거나, 아직 검사 전인 발화가 있으면 더 클 수 있습니다.

data.quality.final_quality.expires_atstring

후보 음원·검사 결과를 보관하는 만료 시각입니다. 이 시각이 지나면 후보 다운로드가 불가능할 수 있으며, 검사 전에는 null입니다. null 허용.

data.quality.final_quality.queue_elapsed_secnumber

작업이 대기열에서 기다린 시간(초)입니다. 생성 시간과 분리해 지연 원인을 파악할 때 사용합니다.

data.quality.final_quality.generation_elapsed_secnumber

실제 음성 생성에 걸린 시간(초)입니다. 대기 시간을 제외한 처리 시간입니다.

data.quality.final_quality.utterancesarray

발화별 품질 검사 결과 목록입니다. 각 항목은 발화 ID·후보 ID·속도·반복·참조 검사 값을 포함합니다.

data.quality.final_quality.utterances[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.final_quality.utterances[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.final_quality.utterances[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.final_quality.utterances[].statusstring

data.quality.final_quality.utterances[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.final_quality.utterances[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.final_quality.utterances[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.final_quality.utterances[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.final_quality.utterances[].reasonsarray

data.quality.final_quality.utterances[].speech_rateobject

data.quality.final_quality.utterances[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.final_quality.utterances[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.final_quality.utterances[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.final_quality.utterances[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.utterances[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.final_quality.utterances[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.final_quality.utterances[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.utterances[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.final_quality.utterances[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.final_quality.utterances[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.final_quality.utterances[].speech_rate.statusstring

data.quality.final_quality.utterances[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.final_quality.utterances[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.final_quality.utterances[].audio_availableboolean

data.quality.final_quality.utterances[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.final_quality.utterances[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.final_quality.utterances[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.final_quality.utterances[].repeatobject

data.quality.final_quality.utterances[].repeat.detectedboolean

data.quality.final_quality.utterances[].repeat.suspectedboolean

data.quality.final_quality.utterances[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.utterances[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.utterances[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.utterances[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.utterances[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.utterances[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.utterances[].reference_intrusionobject

data.quality.final_quality.utterances[].reference_intrusion.detectedboolean

data.quality.final_quality.utterances[].reference_intrusion.suspectedboolean

data.quality.final_quality.utterances[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.utterances[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.utterances[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.utterances[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.utterances[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.utterances[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.utterances[].text_qa_statusstring

data.quality.final_quality.utterances[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.final_quality.utterances[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.final_quality.utterances[].tail_guard_attachedboolean

data.quality.final_quality.utterances[].tail_verifiedboolean

data.quality.final_quality.utterances[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.final_quality.utterances[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.final_quality.utterances[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.final_quality.utterances[].generation_budget_exhaustedboolean

data.quality.final_quality.utterances[].retry_requires_new_regeneration_keyboolean

data.quality.final_quality.utterances[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.final_quality.candidatesarray

음성 후보별 품질 검사 결과 목록입니다. 같은 발화의 여러 후보를 비교해 최종 후보를 고를 때 사용합니다.

data.quality.final_quality.candidates[].idstring

이 검사 항목의 식별자입니다. 같은 응답 안에서 항목을 구분할 때 사용하며, 발화 ID와 다를 수 있습니다.

data.quality.final_quality.candidates[].utterance_idstring

검사 대상 발화의 식별자입니다. 요청의 utterances 순서대로 u001·u002처럼 부여되며, 같은 발화의 여러 후보를 묶을 때 사용합니다.

data.quality.final_quality.candidates[].candidate_idstring

생성된 음성 후보의 식별자입니다. 같은 발화에 후보가 여러 개일 때 각 후보를 구분하며, 후보 오디오 경로에 사용합니다.

data.quality.final_quality.candidates[].statusstring

data.quality.final_quality.candidates[].attemptinteger

이 후보를 생성한 시도 회차입니다. 1부터 시작하며 재생성할 때마다 증가합니다.

data.quality.final_quality.candidates[].voice_idstring

합성에 사용한 공개 목소리 ID입니다. 요청의 voice_id와 같으며, 목소리 목록 API에서 확인한 값을 그대로 반영합니다.

data.quality.final_quality.candidates[].created_atstring

이 발화·후보가 생성된 시각입니다. ISO 8601 형식이며 시간대가 포함됩니다.

data.quality.final_quality.candidates[].elapsed_secnumber

이 항목의 생성·검사에 걸린 경과 시간(초)입니다. 대기열에서 기다린 시간은 포함하지 않을 수 있습니다.

data.quality.final_quality.candidates[].reasonsarray

data.quality.final_quality.candidates[].speech_rateobject

data.quality.final_quality.candidates[].speech_rate.charactersinteger

검사 대상 발화의 글자 수입니다. 공백과 문장부호를 포함하며, chars와 같은 값을 다른 이름으로 제공합니다.

data.quality.final_quality.candidates[].speech_rate.charsinteger

검사 대상 발화의 글자 수입니다. characters와 동일한 값이며, 기존 클라이언트 호환을 위해 함께 제공됩니다.

data.quality.final_quality.candidates[].speech_rate.duration_secnumber

측정된 음성의 실제 길이(초)입니다. 무음 구간이 포함될 수 있고, 초당 글자 수 계산의 기준이 됩니다.

data.quality.final_quality.candidates[].speech_rate.duration_msnumber

측정된 음성의 실제 길이(밀리초)입니다. duration_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.candidates[].speech_rate.cpsnumber

초당 발화 글자 수입니다. 값이 높을수록 빠르게 말한 것이며, min_cps보다 낮으면 지나치게 느린 발화로 판정될 수 있습니다.

data.quality.final_quality.candidates[].speech_rate.expected_secnumber

같은 글자 수를 기준 속도로 읽었을 때 예상되는 발화 길이(초)입니다. 실제 길이와 비교해 속도 편차를 계산합니다.

data.quality.final_quality.candidates[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초)입니다. expected_sec와 같은 값을 단위만 바꿔 제공합니다.

data.quality.final_quality.candidates[].speech_rate.duration_rationumber

실제 음성 길이를 예상 길이로 나눈 비율입니다. 1보다 크면 예상보다 느리고, 1보다 작으면 빠릅니다. 계산할 수 없으면 null입니다. null 허용.

data.quality.final_quality.candidates[].speech_rate.min_cpsnumber

이 검사에서 허용하는 최소 초당 글자 수입니다. cps가 이 값보다 낮으면 속도 검사에서 주의·실패로 표시됩니다.

data.quality.final_quality.candidates[].speech_rate.minimum_charactersinteger

속도 검사를 수행하는 데 필요한 최소 글자 수입니다. 이보다 짧은 발화는 속도 판정을 생략할 수 있습니다.

data.quality.final_quality.candidates[].speech_rate.statusstring

data.quality.final_quality.candidates[].audio_sha256string

후보 음원의 SHA-256 해시입니다. 같은 음원인지 무결성을 비교할 때 사용하며, 음원이 없으면 생략됩니다.

data.quality.final_quality.candidates[].audio_duration_msnumber

후보 음원의 실제 길이(밀리초)입니다. 발화 속도·무음 구간 검사의 기준 값으로 사용됩니다.

data.quality.final_quality.candidates[].audio_availableboolean

data.quality.final_quality.candidates[].transcriptstring

후보 음원에서 음성 인식으로 얻은 텍스트입니다. 원문과 비교해 CER·coverage를 계산합니다.

data.quality.final_quality.candidates[].cernumber

문자 오류율(Character Error Rate)입니다. 0에 가까울수록 원문과 정확히 일치하며, 1 이상이면 많은 문자가 틀렸다는 뜻입니다.

data.quality.final_quality.candidates[].coveragenumber

원문 글자 중 음성에서 실제로 인식된 비율입니다. 1에 가까울수록 원문을 빠짐없이 읽었습니다.

data.quality.final_quality.candidates[].repeatobject

data.quality.final_quality.candidates[].repeat.detectedboolean

data.quality.final_quality.candidates[].repeat.suspectedboolean

data.quality.final_quality.candidates[].repeat.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.candidates[].repeat.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.candidates[].repeat.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.candidates[].repeat.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.candidates[].repeat.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.candidates[].repeat.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.candidates[].reference_intrusionobject

data.quality.final_quality.candidates[].reference_intrusion.detectedboolean

data.quality.final_quality.candidates[].reference_intrusion.suspectedboolean

data.quality.final_quality.candidates[].reference_intrusion.correlationnumber

비교한 두 구간의 파형 유사도입니다. 0~1 범위이며 1에 가까울수록 같은 음성 패턴으로 판단합니다.

data.quality.final_quality.candidates[].reference_intrusion.best_lag_secnumber

두 구간이 가장 잘 일치한 시간 차이(초)입니다. 반복·참조 구간의 기준 위치를 해석할 때 사용합니다.

data.quality.final_quality.candidates[].reference_intrusion.window_start_secnumber

검사한 비교 구간의 시작 시각(초)입니다. 음성 파일 시작점을 0으로 계산합니다.

data.quality.final_quality.candidates[].reference_intrusion.window_end_secnumber

검사한 비교 구간의 끝 시각(초)입니다. window_start_sec와 함께 실제 비교 범위를 나타냅니다.

data.quality.final_quality.candidates[].reference_intrusion.matched_charactersinteger

비교 구간에서 일치한 글자 수입니다. 값이 클수록 반복·참조된 발화가 길다는 뜻입니다.

data.quality.final_quality.candidates[].reference_intrusion.matched_charsinteger

일치한 글자 수를 characters와 같은 방식으로 제공하는 호환 필드입니다. matched_characters와 동일한 값입니다.

data.quality.final_quality.candidates[].text_qa_statusstring

data.quality.final_quality.candidates[].active_start_msnumber

음원에서 실제 발화가 시작된 위치(밀리초)입니다. 앞부분 무음 구간을 제외한 유효 음성의 시작점입니다.

data.quality.final_quality.candidates[].active_end_msnumber

음원에서 실제 발화가 끝난 위치(밀리초)입니다. 뒷부분 무음·보호 구간을 제외한 유효 음성의 끝점입니다.

data.quality.final_quality.candidates[].tail_guard_attachedboolean

data.quality.final_quality.candidates[].tail_verifiedboolean

data.quality.final_quality.candidates[].tail_verified_at_msnumber

끝부분 검증을 수행한 시각(밀리초)입니다. 검증 전에는 null이며, 값이 있으면 tail_verified와 함께 확인하세요. null 허용.

data.quality.final_quality.candidates[].tail_body_end_at_msnumber

보호 구간을 제외한 실제 본문의 끝 위치(밀리초)입니다. 잘림 판정의 기준점으로 사용됩니다. null 허용.

data.quality.final_quality.candidates[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록입니다. 어느 구간까지 끝단 검사를 적용했는지 확인할 때 사용합니다.

data.quality.final_quality.candidates[].generation_budget_exhaustedboolean

data.quality.final_quality.candidates[].retry_requires_new_regeneration_keyboolean

data.quality.final_quality.candidates[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다. 숫자로 오며, 단위·범위는 같은 응답의 다른 필드나 이 문서의 설명을 확인하세요.

data.quality.final_quality.statusstring

data.quality.final_quality.audio_sha256string

최종 선택된 음원의 SHA-256 해시입니다. 다운로드한 파일의 무결성을 확인할 때 사용합니다.

data.error.codestring

작업 실패의 공개 오류코드입니다. 같은 코드는 같은 원인을 뜻하며, 재시도 가능 여부는 오류 문서를 확인하세요.

data.error.messagestring

작업 실패 내용을 사람이 읽을 수 있게 설명합니다. 상세 원인은 서버 로그에만 남으며, 고객에게는 이 문구를 안내하세요.

11API 요청

POST/rest/tts/quote

Bearer 인증
multipart/form-data
JSON 응답

요청 예제

printf '%s\r\n' '--apick-empty--' | curl --fail-with-body --request POST 'https://apick.app/rest/tts/quote' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --header 'Content-Type: multipart/form-data; boundary=apick-empty' \
  --data-binary @-

printf '%s\r\n' '--apick-empty--' | curl --fail-with-body --request POST 'https://apick.app/rest/tts/quote' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --header 'Content-Type: multipart/form-data; boundary=apick-empty' \
  --data-binary @-

POSIX 셸 · APICK_API_KEY 환경변수를 먼저 설정하세요. Windows에서는 Unicode 지원 cURL을 사용하세요.

const form = new FormData();
const response = await fetch("https://apick.app/rest/tts/quote", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
console.log(result);

const form = new FormData();
const response = await fetch("https://apick.app/rest/tts/quote", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
  signal: AbortSignal.timeout(120_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const result = await response.json();
if (result.error || result.data?.error || result.result?.error || result.success === false || result.api?.success === false) {
  throw new Error(JSON.stringify(result));
}
console.log(result);

Node.js 22+ · 서버에서 실행하는 ESM 예제입니다. 키를 브라우저에 넣지 마세요.

import os
import requests
response = requests.request("POST", "https://apick.app/rest/tts/quote",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"], "Content-Type": "multipart/form-data; boundary=apick-empty"},
    data=b"--apick-empty--\r\n",
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

import os
import requests
response = requests.request("POST", "https://apick.app/rest/tts/quote",
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"], "Content-Type": "multipart/form-data; boundary=apick-empty"},
    data=b"--apick-empty--\r\n",
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
if result.get("error") or (isinstance(result.get("data"), dict) and result["data"].get("error")) or (isinstance(result.get("result"), dict) and result["result"].get("error")) or result.get("success") is False or (result.get("api") or {}).get("success") is False:
    raise RuntimeError(result)
print(result)

Python 3 · requests 설치가 필요합니다. 키는 서버 환경변수로 읽습니다.

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$headers[] = "Content-Type: multipart/form-data; boundary=apick-empty";
$form = "--apick-empty--\r\n";
$curl = curl_init('https://apick.app/rest/tts/quote');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
print_r($result);

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$headers[] = "Content-Type: multipart/form-data; boundary=apick-empty";
$form = "--apick-empty--\r\n";
$curl = curl_init('https://apick.app/rest/tts/quote');
curl_setopt_array($curl, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POSTFIELDS => $form,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120,
]);
$body = curl_exec($curl);
if ($body === false) { throw new RuntimeException(curl_error($curl)); }
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
if ($status >= 400) { throw new RuntimeException($body); }
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if (!empty($result["error"]) || !empty($result["data"]["error"]) || !empty($result["result"]["error"]) || ($result["success"] ?? true) === false || ($result["api"]["success"] ?? true) === false) {
    throw new RuntimeException($body);
}
print_r($result);

PHP 8 · cURL 확장이 필요합니다. 키는 서버 환경변수로 읽습니다.

응답 예시

공개된 정적 응답 예제가 없는 경로입니다. 왼쪽 응답 필드에서 제공 범위를 확인하세요.

요청 파라미터 15개

파라미터

설명

textstring조건부

합성할 한국어 본문. text와 utterances 중 하나만 사용합니다. 정규화(normalize_text)를 쓰면 1~2,000자, 끄면 8,000자까지입니다(공백·줄바꿈 포함).

voice_idstring선택

사용할 목소리의 ID입니다. 목소리 목록에서 고른 값을 넣으며, 생략하면 엔진 기본 목소리로 합성됩니다. 목소리별로 억양·속도·성별이 다릅니다.

stylestring선택

자유 서술 낭독 스타일 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.

최대 길이: 1000자

emotionstring선택

허용값: neutral calm cheerful excited sad serious friendly empathetic confident gentle whisper narration

tonestring선택

허용값: narration news audiobook documentary ad conversation announcement tutorial storytelling

accentstring선택

허용값: standard seoul gyeongsang jeolla chungcheong

pacenumber선택

말 속도 배율 0.5~2.0. 1이 기본 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

pitchnumber선택

음높이 -12~12 반음. 0이 기본 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

volume_gain_dbnumber선택

음량 보정 -12~12 dB. 0이 기본 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다.

normalize_textboolean선택

multi_speakerboolean선택

speakersobject선택

화자 이름 → {voice_id, style, emotion, tone, accent, pace, pitch, volume_gain_db}

utterancesarray조건부

합성할 발화(문단) 목록입니다. 각 항목은 text·speaker·speed 등을 가지며, 전체 글자 수 제한을 함께 확인하세요.

utterances[0][text]string조건부

발화 본문. text와 utterances 중 하나만 사용합니다. 최대 100개 발화입니다. 본문 합계는 정규화(normalize_text)를 쓰면 2,000자, 끄면 8,000자까지입니다.

utterances[0][voice_id]string선택

이 발화에만 쓸 목소리 ID입니다. 생략하면 화자 설정, 그다음 최상위 voice_id를 씁니다.

응답 필드 9개

응답 필드

설명

dataobject

data.job_idstring

접수 응답에서 받은 작업 ID. 같은 계정의 작업에만 접근할 수 있습니다.

data.statusstring

허용값: waiting

data.voice_idstring

합성에 사용한 목소리 ID입니다. 요청의 voice_id를 그대로 반영하며, 생략한 경우 엔진 기본 목소리 ID가 옵니다.

data.character_countinteger

공백·문장부호를 포함한 합성 글자 수입니다. 이 값으로 과금 글자 수를 확인하며, 발화 목록을 쓰면 전체 발화의 합입니다.

apiobject

api.successboolean

api.costnumber

api.pl_idinteger

입력 조건·전송 규칙

목소리·표현 옵션

요청 옵션

동작

voice_id

엔진별 목소리 목록의 ID입니다. Gemini 기본값은 Kore, ChatGPT 기본값은 alloy입니다. 대소문자는 구분하지 않습니다.

style

낭독 스타일을 문장으로 지정합니다(최대 1,000자). 예: 차분한 뉴스 낭독, 낮고 천천히. 생략하면 기본 낭독입니다.

emotion

감정 표현. neutral, calm, cheerful, excited, sad, serious, friendly, empathetic, confident, gentle, whisper, narration 중 하나입니다.

tone

용도·톤. narration, news, audiobook, documentary, ad, conversation, announcement, tutorial, storytelling 중 하나입니다.

accent

억양. standard(기본), seoul, gyeongsang, jeolla, chungcheong 중 하나입니다.

pace

말 속도 배율 0.5~2.0입니다. 1이 기본이며 작을수록 느립니다.

pitch

음높이를 반음 단위 -12~12로 조정합니다. 0이 기본입니다.

volume_gain_db

음량 보정을 dB 단위 -12~12로 지정합니다. 0이 기본입니다.

speakers·multi_speaker

화자 이름별로 목소리·옵션을 묶어 대화를 만듭니다(최대 8명). Gemini는 화자 2명의 대화를 한 번에, ChatGPT는 발화마다 목소리를 바꿔 읽습니다. 결과는 둘 다 MP3 하나와 ASS 하나입니다.

normalize_text: true

기본값. 한글 표기 정규화로 숫자·단위·기호·영문 약어를 문맥에 맞는 읽기로 바꿉니다(예: 5번 버스 → 오 번 버스, 버튼을 5번 → 다섯 번, -5℃ → 영하 오 도). 정규화 요금이 합산되며 합계 2,000자까지입니다. 자막에는 원문 표기가 그대로 나옵니다.

normalize_text: false

정규화와 그 요금을 생략합니다. 숫자·영문은 원하는 읽기대로 한글로 풀어 써서 보내세요. 합계 8,000자까지입니다.

표현 옵션은 낭독 지시이므로 목소리마다 효과가 다릅니다. ChatGPT 엔진에서 pace·pitch·volume_gain_db는 느리게·높게·크게 같은 방향으로 반영되며 정확한 배율·반음·dB를 보장하지 않습니다. 엔진별로 쓸 수 있는 값은 GET /rest/tts/options에서 확인하세요.

목소리 목록의 age_verified가 false인 목소리는 연령대가 확인되지 않은 것입니다. 연령대 표시는 목소리 설정이며 실제 화자의 나이를 뜻하지 않습니다.

항목

설정

메서드·주소

POST https://apick.app/rest/tts/jobs (ChatGPT 엔진은 /rest/tts/openai/jobs)

인증 헤더

Authorization: Bearer 내 계정의 API 인증키

본문 형식

application/json 또는 multipart/form-data

재접수 키(선택)

X-Idempotency-Key 헤더. 영문·숫자·_ . : - 1~128자. 접수 응답을 받지 못했을 때 같은 키·같은 입력으로 다시 보내면 새로 만들지 않고 처음 작업을 돌려줍니다. 같은 키로 입력을 바꾸면 409입니다.

발화별 style·speaker·emotion·tone·accent·pace·pitch·volume_gain_db와 speakers는 form-data 본문에서만 받습니다. form-data로 보낼 때는 최상위 옵션과 utterances[n][text]·utterances[n][voice_id]만 쓰세요. 위에 없는 이름의 옵션, SSML, 문장 중간 무음 지시는 지원하지 않습니다.

요청 예시

form-data 전체 예제 보기

한국어 AI 내레이션 TTS API

대본만 주면 내레이션과 자막이 함께 나옵니다

도입 효과

이런 곳에서 많이 씁니다

알아둘 점

이용 전 확인

지원 API 요약

요금

대본 작성 가이드

1. 문장부호로 쉼과 억양 정하기

2. 숫자·날짜·단위

3. 발화 나누기와 글자 수

4. 감정·톤·속도·음높이

5. 여러 화자의 대화

요청과 응답

1작업 접수

요청 파라미터 15개

응답 필드 9개

2작업 접수

요청 파라미터 15개

응답 필드 9개

3작업 접수

요청 파라미터 15개

응답 필드 9개

4상태·목록 조회

요청 파라미터 없음

응답 필드 263개

5작업 취소

요청 파라미터 없음

응답 필드 7개

6결과 받기

요청 파라미터 없음

응답 필드 파일

7결과 받기

요청 파라미터 없음

응답 필드 파일

8상태·목록 조회

요청 파라미터 없음

응답 필드 263개

9상태·목록 조회

요청 파라미터 없음

응답 필드 263개

10상태·목록 조회

요청 파라미터 없음

응답 필드 263개

11API 요청

요청 파라미터 15개

응답 필드 9개

입력 조건·전송 규칙

목소리·표현 옵션

요청 예시

사용 예시

예시 1. 대본 한 편을 기본 목소리로 접수

예시 2. 정규화를 끄고 읽는 법을 직접 정하기

예시 3. 문장마다 다른 목소리로 읽기

예시 4. ChatGPT 음성으로 접수

예시 5. 접수 전에 예상 요금 확인

예시 6. 상태 확인 후 MP3 내려받기

응답 처리

응답과 정산

응답 예시 (완료된 작업 조회)

오류 코드

이 API의 오류 코드 12개

서비스 코드·조건

작업 상태

오류 코드

폼 입력 오류 error.code

요금·이용 조건

연동 팁