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

요청과 응답

작업 접수 예제직접 실행하지 않습니다POST /rest/tts/jobs

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

curl --fail-with-body --request POST 'https://apick.app/rest/tts/jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'voice_id=v2_ann_m_30s_01' \
  --form-string 'text=오늘 들려드릴 이야기는 한 사람의 선택에서 시작됩니다.'

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

const form = new FormData();
form.append("voice_id", "v2_ann_m_30s_01");
form.append("text", "오늘 들려드릴 이야기는 한 사람의 선택에서 시작됩니다.");
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);

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

import os
import requests
parts = [
    ("voice_id", (None, "v2_ann_m_30s_01")),
    ("text", (None, "오늘 들려드릴 이야기는 한 사람의 선택에서 시작됩니다.")),
]
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)

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

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'voice_id' => 'v2_ann_m_30s_01',
    'text' => '오늘 들려드릴 이야기는 한 사람의 선택에서 시작됩니다.',
];
$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);

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

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=v2_ann_m_30s_01' \
  --form-string 'text=오늘 들려드릴 이야기는 한 사람의 선택에서 시작됩니다.'

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

const form = new FormData();
form.append("voice_id", "v2_ann_m_30s_01");
form.append("text", "오늘 들려드릴 이야기는 한 사람의 선택에서 시작됩니다.");
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);

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

import os
import requests
parts = [
    ("voice_id", (None, "v2_ann_m_30s_01")),
    ("text", (None, "오늘 들려드릴 이야기는 한 사람의 선택에서 시작됩니다.")),
]
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)

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

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'voice_id' => 'v2_ann_m_30s_01',
    'text' => '오늘 들려드릴 이야기는 한 사람의 선택에서 시작됩니다.',
];
$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);

1. 작업 접수

POST/rest/tts/jobs

Bearer 인증 · multipart/form-data · JSON 응답

입력 항목

폼 항목·타입

필수

설명·예제

voice_idstring

필수

지원 voice_id허용값: v2_ann_m_30s_01, v2_ann_m_30s_02, v2_ann_m_30s_04, v2_ann_m_30s_05, v2_ann_f_30s_01, v2_ann_f_30s_02, v2_ann_f_30s_03, v2_ann_f_30s_04, v2_ann_f_30s_05, v2_m_teen_01, v2_m_young_01, v2_m_mid_01, v2_m_senior_01, v2_f_teen_01, v2_f_young_01, v2_f_senior_01예: v2_ann_m_30s_01

textstring

조건부

합성할 한국어 본문. text와 utterances 중 하나만 사용합니다. 전체 1~800자(공백·줄바꿈 포함).최대 길이: 800예: 오늘 들려드릴 이야기는 한 사람의 선택에서 시작됩니다.

utterancesarray

선택

발화 객체 배열(1~100개). 전체 text 합계 최대 800자. text와 동시 사용 불가

utterances[0][text]string

조건부

발화 본문. text와 utterances 중 하나만 사용합니다. 최대 100개 발화, 전체 본문 합계 800자입니다.

utterances[0][paragraph_id]string

선택

발화가 속한 문단 식별자입니다.

utterances[0][pause_after]string

선택

발화 뒤 쉼. none=없음, micro=짧은 쉼, normal=보통, strong=긴 쉼, paragraph=문단 경계. 생략하면 문맥에 맞춰 자동 지정합니다.허용값: none, micro, normal, strong, paragraph

utterances[0][pause_before_ms]integer

선택

발화 앞 쉼의 길이. 밀리초 단위 정수 0~10000.최솟값: 0최댓값: 10000

응답과 성공 판정

HTTP 성공과 업무 결과를 구분하세요. 아래 서비스별 결과 필드가 실제 성공·실패를 나타냅니다.

응답 상태

{
  "data": {
    "job_id": "7f7e43f578cd459db04696416435c789",
    "status": "waiting",
    "voice_id": "v2_ann_m_30s_01",
    "character_count": 27
  },
  "api": {
    "success": true,
    "cost": 10,
    "pl_id": 12345
  }
}

필드·타입

의미·조건

dataobject

아래 하위 항목을 확인하세요.

data.job_idstring

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

data.statusstring

접수 완료.허용값: waiting

data.voice_idstring

선택한 목소리 ID.

data.character_countinteger

공백·문장부호를 포함한 합성 글자 수.

apiobject

호출 메타데이터.

api.successboolean

API 공통 처리 여부. HTTP 상태·업무 결과와 함께 확인합니다.

api.costnumber

이번 호출에서 차감한 포인트. 무료 조회·재전송은 0.

api.pl_idinteger

과금 기록 ID. 과금 기록이 있을 때만 포함합니다.

정적 연동 예시입니다. 실제 계정·개인정보를 조회하지 않습니다.

상태·목록 조회 예제직접 실행하지 않습니다GET /rest/tts/jobs/:job_id

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

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

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

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);

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

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)

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

<?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);

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

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 120

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

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);

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

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)

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

<?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);

2. 상태·목록 조회

GET/rest/tts/jobs/:job_id

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

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

입력 항목

추가 폼 항목이 없습니다. 인증 헤더는 필요합니다.

응답과 성공 판정

HTTP 성공과 업무 결과를 구분하세요. 아래 서비스별 결과 필드가 실제 성공·실패를 나타냅니다.

응답 상태

{
  "data": {
    "job_id": "7f7e43f578cd459db04696416435c789",
    "status": "completed",
    "result_available": true,
    "subtitles_available": true
  },
  "api": {
    "success": true,
    "cost": 0
  }
}

필드·타입

의미·조건

dataobject

아래 하위 항목을 확인하세요.

data.job_idstring

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

data.statusstring

작업 진행 상태. 완료 여부와 다운로드 가능 여부를 함께 확인합니다.허용값: waiting, processing, completed, cancelled, failed

data.result_availableboolean

최종 MP3를 내려받을 수 있는지 여부.

data.subtitles_availableboolean

자막을 내려받을 수 있는지 여부.

data.resume_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다.

data.qualityobject

품질 상세. 아직 검사 전이면 null이거나 생략됩니다. null 허용.

data.quality.schema_versionstring

품질 결과 규격 버전.

data.quality.attemptinteger

현재 검사 시도 회차.

data.quality.phasestring

현재 처리 단계.

data.quality.accepted_utterancesinteger

통과 발화 수.

data.quality.failed_utterancesinteger

실패 발화 수.

data.quality.total_utterancesinteger

전체 발화 수.

data.quality.expires_atstring

후보 결과 보관 만료 일시. null 허용.

data.quality.queue_elapsed_secnumber

대기 시간(초).

data.quality.generation_elapsed_secnumber

생성 시간(초).

data.quality.utterancesarray

발화별 검사 결과.

data.quality.utterances[].idstring

발화 식별자.

data.quality.utterances[].utterance_idstring

발화 식별자. 예: u001.

data.quality.utterances[].candidate_idstring

음성 후보 식별자.

data.quality.utterances[].statusstring

항목 처리 또는 검사 상태.

data.quality.utterances[].attemptinteger

생성 시도 회차.

data.quality.utterances[].voice_idstring

요청한 공개 목소리 ID.

data.quality.utterances[].created_atstring

항목 생성 일시.

data.quality.utterances[].elapsed_secnumber

처리 경과 시간(초).

data.quality.utterances[].reasonsarray

검사·실패 사유 목록. 사유가 없으면 빈 배열입니다.

data.quality.utterances[].speech_rateobject

발화 속도 검사. 검사 단계에 따라 일부 필드는 생략됩니다.

data.quality.utterances[].speech_rate.charactersinteger

발화 글자 수.

data.quality.utterances[].speech_rate.charsinteger

발화 글자 수.

data.quality.utterances[].speech_rate.duration_secnumber

측정 음성 길이(초).

data.quality.utterances[].speech_rate.duration_msnumber

측정 음성 길이(밀리초).

data.quality.utterances[].speech_rate.cpsnumber

초당 발화 글자 수.

data.quality.utterances[].speech_rate.expected_secnumber

예상 발화 길이(초).

data.quality.utterances[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초).

data.quality.utterances[].speech_rate.duration_rationumber

실제 길이/예상 길이 비율. 계산할 수 없으면 null. null 허용.

data.quality.utterances[].speech_rate.min_cpsnumber

최소 허용 초당 글자 수.

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

음원에서 인식한 텍스트.

data.quality.utterances[].cernumber

문자 오류율. 낮을수록 원문과 가깝습니다.

data.quality.utterances[].coveragenumber

원문에 대한 음성의 포함률.

data.quality.utterances[].repeatobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

data.quality.utterances[].repeat.detectedboolean

해당 현상이 검출됐는지 여부.

data.quality.utterances[].repeat.suspectedboolean

추가 확인이 필요한지 여부.

data.quality.utterances[].repeat.correlationnumber

비교 구간의 상관도.

data.quality.utterances[].repeat.best_lag_secnumber

가장 잘 일치한 시간 차(초).

data.quality.utterances[].repeat.window_start_secnumber

검사 구간 시작(초).

data.quality.utterances[].repeat.window_end_secnumber

검사 구간 끝(초).

data.quality.utterances[].repeat.matched_charactersinteger

일치한 글자 수.

data.quality.utterances[].repeat.matched_charsinteger

일치한 글자 수.

data.quality.utterances[].reference_intrusionobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

data.quality.utterances[].reference_intrusion.detectedboolean

해당 현상이 검출됐는지 여부.

data.quality.utterances[].reference_intrusion.suspectedboolean

추가 확인이 필요한지 여부.

data.quality.utterances[].reference_intrusion.correlationnumber

비교 구간의 상관도.

data.quality.utterances[].reference_intrusion.best_lag_secnumber

가장 잘 일치한 시간 차(초).

data.quality.utterances[].reference_intrusion.window_start_secnumber

검사 구간 시작(초).

data.quality.utterances[].reference_intrusion.window_end_secnumber

검사 구간 끝(초).

data.quality.utterances[].reference_intrusion.matched_charactersinteger

일치한 글자 수.

data.quality.utterances[].reference_intrusion.matched_charsinteger

일치한 글자 수.

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. 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

발화 식별자.

data.quality.candidates[].utterance_idstring

발화 식별자. 예: u001.

data.quality.candidates[].candidate_idstring

음성 후보 식별자.

data.quality.candidates[].statusstring

항목 처리 또는 검사 상태.

data.quality.candidates[].attemptinteger

생성 시도 회차.

data.quality.candidates[].voice_idstring

요청한 공개 목소리 ID.

data.quality.candidates[].created_atstring

항목 생성 일시.

data.quality.candidates[].elapsed_secnumber

처리 경과 시간(초).

data.quality.candidates[].reasonsarray

검사·실패 사유 목록. 사유가 없으면 빈 배열입니다.

data.quality.candidates[].speech_rateobject

발화 속도 검사. 검사 단계에 따라 일부 필드는 생략됩니다.

data.quality.candidates[].speech_rate.charactersinteger

발화 글자 수.

data.quality.candidates[].speech_rate.charsinteger

발화 글자 수.

data.quality.candidates[].speech_rate.duration_secnumber

측정 음성 길이(초).

data.quality.candidates[].speech_rate.duration_msnumber

측정 음성 길이(밀리초).

data.quality.candidates[].speech_rate.cpsnumber

초당 발화 글자 수.

data.quality.candidates[].speech_rate.expected_secnumber

예상 발화 길이(초).

data.quality.candidates[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초).

data.quality.candidates[].speech_rate.duration_rationumber

실제 길이/예상 길이 비율. 계산할 수 없으면 null. null 허용.

data.quality.candidates[].speech_rate.min_cpsnumber

최소 허용 초당 글자 수.

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

음원에서 인식한 텍스트.

data.quality.candidates[].cernumber

문자 오류율. 낮을수록 원문과 가깝습니다.

data.quality.candidates[].coveragenumber

원문에 대한 음성의 포함률.

data.quality.candidates[].repeatobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

data.quality.candidates[].repeat.detectedboolean

해당 현상이 검출됐는지 여부.

data.quality.candidates[].repeat.suspectedboolean

추가 확인이 필요한지 여부.

data.quality.candidates[].repeat.correlationnumber

비교 구간의 상관도.

data.quality.candidates[].repeat.best_lag_secnumber

가장 잘 일치한 시간 차(초).

data.quality.candidates[].repeat.window_start_secnumber

검사 구간 시작(초).

data.quality.candidates[].repeat.window_end_secnumber

검사 구간 끝(초).

data.quality.candidates[].repeat.matched_charactersinteger

일치한 글자 수.

data.quality.candidates[].repeat.matched_charsinteger

일치한 글자 수.

data.quality.candidates[].reference_intrusionobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

data.quality.candidates[].reference_intrusion.detectedboolean

해당 현상이 검출됐는지 여부.

data.quality.candidates[].reference_intrusion.suspectedboolean

추가 확인이 필요한지 여부.

data.quality.candidates[].reference_intrusion.correlationnumber

비교 구간의 상관도.

data.quality.candidates[].reference_intrusion.best_lag_secnumber

가장 잘 일치한 시간 차(초).

data.quality.candidates[].reference_intrusion.window_start_secnumber

검사 구간 시작(초).

data.quality.candidates[].reference_intrusion.window_end_secnumber

검사 구간 끝(초).

data.quality.candidates[].reference_intrusion.matched_charactersinteger

일치한 글자 수.

data.quality.candidates[].reference_intrusion.matched_charsinteger

일치한 글자 수.

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. 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

최종 결과 검사. 최종 검사 전에는 생략됩니다.

data.quality.final_quality.schema_versionstring

품질 결과 규격 버전.

data.quality.final_quality.attemptinteger

현재 검사 시도 회차.

data.quality.final_quality.phasestring

현재 처리 단계.

data.quality.final_quality.accepted_utterancesinteger

통과 발화 수.

data.quality.final_quality.failed_utterancesinteger

실패 발화 수.

data.quality.final_quality.total_utterancesinteger

전체 발화 수.

data.quality.final_quality.expires_atstring

후보 결과 보관 만료 일시. null 허용.

data.quality.final_quality.queue_elapsed_secnumber

대기 시간(초).

data.quality.final_quality.generation_elapsed_secnumber

생성 시간(초).

data.quality.final_quality.utterancesarray

발화별 검사 결과.

data.quality.final_quality.utterances[].idstring

발화 식별자.

data.quality.final_quality.utterances[].utterance_idstring

발화 식별자. 예: u001.

data.quality.final_quality.utterances[].candidate_idstring

음성 후보 식별자.

data.quality.final_quality.utterances[].statusstring

항목 처리 또는 검사 상태.

data.quality.final_quality.utterances[].attemptinteger

생성 시도 회차.

data.quality.final_quality.utterances[].voice_idstring

요청한 공개 목소리 ID.

data.quality.final_quality.utterances[].created_atstring

항목 생성 일시.

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

발화 글자 수.

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

발화 글자 수.

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

측정 음성 길이(초).

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

측정 음성 길이(밀리초).

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

초당 발화 글자 수.

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

예상 발화 길이(초).

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

예상 발화 길이(밀리초).

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

실제 길이/예상 길이 비율. 계산할 수 없으면 null. null 허용.

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

최소 허용 초당 글자 수.

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

음원에서 인식한 텍스트.

data.quality.final_quality.utterances[].cernumber

문자 오류율. 낮을수록 원문과 가깝습니다.

data.quality.final_quality.utterances[].coveragenumber

원문에 대한 음성의 포함률.

data.quality.final_quality.utterances[].repeatobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

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

해당 현상이 검출됐는지 여부.

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

추가 확인이 필요한지 여부.

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

비교 구간의 상관도.

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

가장 잘 일치한 시간 차(초).

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

검사 구간 시작(초).

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

검사 구간 끝(초).

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

일치한 글자 수.

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

일치한 글자 수.

data.quality.final_quality.utterances[].reference_intrusionobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

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

해당 현상이 검출됐는지 여부.

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

추가 확인이 필요한지 여부.

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

비교 구간의 상관도.

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

가장 잘 일치한 시간 차(초).

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

검사 구간 시작(초).

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

검사 구간 끝(초).

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

일치한 글자 수.

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

일치한 글자 수.

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. 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

발화 식별자.

data.quality.final_quality.candidates[].utterance_idstring

발화 식별자. 예: u001.

data.quality.final_quality.candidates[].candidate_idstring

음성 후보 식별자.

data.quality.final_quality.candidates[].statusstring

항목 처리 또는 검사 상태.

data.quality.final_quality.candidates[].attemptinteger

생성 시도 회차.

data.quality.final_quality.candidates[].voice_idstring

요청한 공개 목소리 ID.

data.quality.final_quality.candidates[].created_atstring

항목 생성 일시.

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

발화 글자 수.

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

발화 글자 수.

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

측정 음성 길이(초).

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

측정 음성 길이(밀리초).

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

초당 발화 글자 수.

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

예상 발화 길이(초).

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

예상 발화 길이(밀리초).

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

실제 길이/예상 길이 비율. 계산할 수 없으면 null. null 허용.

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

최소 허용 초당 글자 수.

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

음원에서 인식한 텍스트.

data.quality.final_quality.candidates[].cernumber

문자 오류율. 낮을수록 원문과 가깝습니다.

data.quality.final_quality.candidates[].coveragenumber

원문에 대한 음성의 포함률.

data.quality.final_quality.candidates[].repeatobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

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

해당 현상이 검출됐는지 여부.

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

추가 확인이 필요한지 여부.

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

비교 구간의 상관도.

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

가장 잘 일치한 시간 차(초).

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

검사 구간 시작(초).

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

검사 구간 끝(초).

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

일치한 글자 수.

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

일치한 글자 수.

data.quality.final_quality.candidates[].reference_intrusionobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

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

해당 현상이 검출됐는지 여부.

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

추가 확인이 필요한지 여부.

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

비교 구간의 상관도.

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

가장 잘 일치한 시간 차(초).

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

검사 구간 시작(초).

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

검사 구간 끝(초).

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

일치한 글자 수.

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

일치한 글자 수.

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. 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.errorobject

실패 상태일 때 포함합니다.

data.error.codestring

실패한 작업의 공개 오류코드.

data.error.messagestring

오류 설명.

apiobject

호출 메타데이터.

api.successboolean

API 공통 처리 여부. HTTP 상태·업무 결과와 함께 확인합니다.

api.costnumber

이번 호출에서 차감한 포인트. 무료 조회·재전송은 0.

api.pl_idinteger

과금 기록 ID. 과금 기록이 있을 때만 포함합니다.

정적 연동 예시입니다. 실제 계정·개인정보를 조회하지 않습니다.

작업 취소 예제직접 실행하지 않습니다POST /rest/tts/jobs/:job_id/cancel

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

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 @-

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

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);

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

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)

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

<?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);

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

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 @-

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

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);

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

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)

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

<?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);

3. 작업 취소

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

Bearer 인증 · multipart/form-data · JSON 응답

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

입력 항목

추가 폼 항목이 없습니다. 인증 헤더는 필요합니다.

응답과 성공 판정

HTTP 성공과 업무 결과를 구분하세요. 아래 서비스별 결과 필드가 실제 성공·실패를 나타냅니다.

응답 상태

{
  "data": {
    "job_id": "7f7e43f578cd459db04696416435c789",
    "status": "cancelled"
  },
  "api": {
    "success": true,
    "cost": 0
  }
}

필드·타입

의미·조건

dataobject

아래 하위 항목을 확인하세요.

data.job_idstring

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

data.statusstring

취소 완료 상태.허용값: cancelled

apiobject

호출 메타데이터.

api.successboolean

API 공통 처리 여부. HTTP 상태·업무 결과와 함께 확인합니다.

api.costnumber

이번 호출에서 차감한 포인트. 무료 조회·재전송은 0.

api.pl_idinteger

과금 기록 ID. 과금 기록이 있을 때만 포함합니다.

정적 연동 예시입니다. 실제 계정·개인정보를 조회하지 않습니다.

결과 받기 예제직접 실행하지 않습니다GET /rest/tts/jobs/:job_id/result

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

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을 확인한 뒤 파일을 사용하세요.

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

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()));

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

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)

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

<?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);

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

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을 확인한 뒤 파일을 사용하세요.

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

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()));

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

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)

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

<?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);

4. 결과 받기

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

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

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

입력 항목

추가 폼 항목이 없습니다. 인증 헤더는 필요합니다.

응답과 성공 판정

HTTP 성공과 업무 결과를 구분하세요. 아래 서비스별 결과 필드가 실제 성공·실패를 나타냅니다.

파일 직접 응답

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

결과 받기 예제직접 실행하지 않습니다GET /rest/tts/jobs/:job_id/subtitles

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

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을 확인한 뒤 파일을 사용하세요.

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

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()));

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

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)

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

<?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);

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

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을 확인한 뒤 파일을 사용하세요.

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

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()));

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

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)

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

<?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);

5. 결과 받기

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

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

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

입력 항목

추가 폼 항목이 없습니다. 인증 헤더는 필요합니다.

응답과 성공 판정

HTTP 성공과 업무 결과를 구분하세요. 아래 서비스별 결과 필드가 실제 성공·실패를 나타냅니다.

파일 직접 응답

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

상태·목록 조회 예제직접 실행하지 않습니다GET /rest/tts/jobs/:job_id/quality

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

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

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

const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/quality`, {
  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);

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

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/tts/jobs/{job_id}/quality".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)

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

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/quality');
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);

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

curl --fail-with-body --request GET "https://apick.app/rest/tts/jobs/${APICK_JOB_ID}/quality" \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120

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

const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/quality`, {
  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);

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

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/tts/jobs/{job_id}/quality".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)

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

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/quality');
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);

6. 상태·목록 조회

GET/rest/tts/jobs/:job_id/quality

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

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

입력 항목

추가 폼 항목이 없습니다. 인증 헤더는 필요합니다.

응답과 성공 판정

HTTP 성공과 업무 결과를 구분하세요. 아래 서비스별 결과 필드가 실제 성공·실패를 나타냅니다.

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

필드·타입

의미·조건

dataobject

아래 하위 항목을 확인하세요.

data.job_idstring

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

data.resume_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다.

data.schema_versionstring

품질 결과 규격 버전.

data.attemptinteger

현재 검사 시도 회차.

data.phasestring

현재 처리 단계.

data.accepted_utterancesinteger

통과 발화 수.

data.failed_utterancesinteger

실패 발화 수.

data.total_utterancesinteger

전체 발화 수.

data.expires_atstring

후보 결과 보관 만료 일시. null 허용.

data.queue_elapsed_secnumber

대기 시간(초).

data.generation_elapsed_secnumber

생성 시간(초).

data.utterancesarray

발화별 검사 결과.

data.utterances[].idstring

발화 식별자.

data.utterances[].utterance_idstring

발화 식별자. 예: u001.

data.utterances[].candidate_idstring

음성 후보 식별자.

data.utterances[].statusstring

항목 처리 또는 검사 상태.

data.utterances[].attemptinteger

생성 시도 회차.

data.utterances[].voice_idstring

요청한 공개 목소리 ID.

data.utterances[].created_atstring

항목 생성 일시.

data.utterances[].elapsed_secnumber

처리 경과 시간(초).

data.utterances[].reasonsarray

검사·실패 사유 목록. 사유가 없으면 빈 배열입니다.

data.utterances[].speech_rateobject

발화 속도 검사. 검사 단계에 따라 일부 필드는 생략됩니다.

data.utterances[].speech_rate.charactersinteger

발화 글자 수.

data.utterances[].speech_rate.charsinteger

발화 글자 수.

data.utterances[].speech_rate.duration_secnumber

측정 음성 길이(초).

data.utterances[].speech_rate.duration_msnumber

측정 음성 길이(밀리초).

data.utterances[].speech_rate.cpsnumber

초당 발화 글자 수.

data.utterances[].speech_rate.expected_secnumber

예상 발화 길이(초).

data.utterances[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초).

data.utterances[].speech_rate.duration_rationumber

실제 길이/예상 길이 비율. 계산할 수 없으면 null. null 허용.

data.utterances[].speech_rate.min_cpsnumber

최소 허용 초당 글자 수.

data.utterances[].speech_rate.minimum_charactersinteger

검사에 필요한 최소 글자 수.

data.utterances[].speech_rate.statusstring

속도 검사 결과.

data.utterances[].audio_sha256string

후보 음원 SHA-256. 동일 음원 확인에 사용합니다.

data.utterances[].audio_duration_msnumber

음원 길이(밀리초).

data.utterances[].audio_availableboolean

후보 음원 다운로드 가능 여부.

data.utterances[].transcriptstring

음원에서 인식한 텍스트.

data.utterances[].cernumber

문자 오류율. 낮을수록 원문과 가깝습니다.

data.utterances[].coveragenumber

원문에 대한 음성의 포함률.

data.utterances[].repeatobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

data.utterances[].repeat.detectedboolean

해당 현상이 검출됐는지 여부.

data.utterances[].repeat.suspectedboolean

추가 확인이 필요한지 여부.

data.utterances[].repeat.correlationnumber

비교 구간의 상관도.

data.utterances[].repeat.best_lag_secnumber

가장 잘 일치한 시간 차(초).

data.utterances[].repeat.window_start_secnumber

검사 구간 시작(초).

data.utterances[].repeat.window_end_secnumber

검사 구간 끝(초).

data.utterances[].repeat.matched_charactersinteger

일치한 글자 수.

data.utterances[].repeat.matched_charsinteger

일치한 글자 수.

data.utterances[].reference_intrusionobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

data.utterances[].reference_intrusion.detectedboolean

해당 현상이 검출됐는지 여부.

data.utterances[].reference_intrusion.suspectedboolean

추가 확인이 필요한지 여부.

data.utterances[].reference_intrusion.correlationnumber

비교 구간의 상관도.

data.utterances[].reference_intrusion.best_lag_secnumber

가장 잘 일치한 시간 차(초).

data.utterances[].reference_intrusion.window_start_secnumber

검사 구간 시작(초).

data.utterances[].reference_intrusion.window_end_secnumber

검사 구간 끝(초).

data.utterances[].reference_intrusion.matched_charactersinteger

일치한 글자 수.

data.utterances[].reference_intrusion.matched_charsinteger

일치한 글자 수.

data.utterances[].text_qa_statusstring

텍스트 검사 상태.

data.utterances[].active_start_msnumber

유효 음성 구간 시작(밀리초).

data.utterances[].active_end_msnumber

유효 음성 구간 끝(밀리초).

data.utterances[].tail_guard_attachedboolean

끝부분 확인용 보호 구간 부착 여부.

data.utterances[].tail_verifiedboolean

끝부분 검증 완료 여부.

data.utterances[].tail_verified_at_msnumber

끝부분을 검증한 시각(밀리초). 검증 전에는 null. null 허용.

data.utterances[].tail_body_end_at_msnumber

본문 끝 위치(밀리초). null 허용.

data.utterances[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록.

data.utterances[].generation_budget_exhaustedboolean

해당 발화의 자동 생성 시도 한도 소진 여부.

data.utterances[].retry_requires_new_regeneration_keyboolean

새 재생성 키가 필요한 상태인지 여부.

data.utterances[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다.

data.candidatesarray

음원 후보별 검사 결과.

data.candidates[].idstring

발화 식별자.

data.candidates[].utterance_idstring

발화 식별자. 예: u001.

data.candidates[].candidate_idstring

음성 후보 식별자.

data.candidates[].statusstring

항목 처리 또는 검사 상태.

data.candidates[].attemptinteger

생성 시도 회차.

data.candidates[].voice_idstring

요청한 공개 목소리 ID.

data.candidates[].created_atstring

항목 생성 일시.

data.candidates[].elapsed_secnumber

처리 경과 시간(초).

data.candidates[].reasonsarray

검사·실패 사유 목록. 사유가 없으면 빈 배열입니다.

data.candidates[].speech_rateobject

발화 속도 검사. 검사 단계에 따라 일부 필드는 생략됩니다.

data.candidates[].speech_rate.charactersinteger

발화 글자 수.

data.candidates[].speech_rate.charsinteger

발화 글자 수.

data.candidates[].speech_rate.duration_secnumber

측정 음성 길이(초).

data.candidates[].speech_rate.duration_msnumber

측정 음성 길이(밀리초).

data.candidates[].speech_rate.cpsnumber

초당 발화 글자 수.

data.candidates[].speech_rate.expected_secnumber

예상 발화 길이(초).

data.candidates[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초).

data.candidates[].speech_rate.duration_rationumber

실제 길이/예상 길이 비율. 계산할 수 없으면 null. null 허용.

data.candidates[].speech_rate.min_cpsnumber

최소 허용 초당 글자 수.

data.candidates[].speech_rate.minimum_charactersinteger

검사에 필요한 최소 글자 수.

data.candidates[].speech_rate.statusstring

속도 검사 결과.

data.candidates[].audio_sha256string

후보 음원 SHA-256. 동일 음원 확인에 사용합니다.

data.candidates[].audio_duration_msnumber

음원 길이(밀리초).

data.candidates[].audio_availableboolean

후보 음원 다운로드 가능 여부.

data.candidates[].transcriptstring

음원에서 인식한 텍스트.

data.candidates[].cernumber

문자 오류율. 낮을수록 원문과 가깝습니다.

data.candidates[].coveragenumber

원문에 대한 음성의 포함률.

data.candidates[].repeatobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

data.candidates[].repeat.detectedboolean

해당 현상이 검출됐는지 여부.

data.candidates[].repeat.suspectedboolean

추가 확인이 필요한지 여부.

data.candidates[].repeat.correlationnumber

비교 구간의 상관도.

data.candidates[].repeat.best_lag_secnumber

가장 잘 일치한 시간 차(초).

data.candidates[].repeat.window_start_secnumber

검사 구간 시작(초).

data.candidates[].repeat.window_end_secnumber

검사 구간 끝(초).

data.candidates[].repeat.matched_charactersinteger

일치한 글자 수.

data.candidates[].repeat.matched_charsinteger

일치한 글자 수.

data.candidates[].reference_intrusionobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

data.candidates[].reference_intrusion.detectedboolean

해당 현상이 검출됐는지 여부.

data.candidates[].reference_intrusion.suspectedboolean

추가 확인이 필요한지 여부.

data.candidates[].reference_intrusion.correlationnumber

비교 구간의 상관도.

data.candidates[].reference_intrusion.best_lag_secnumber

가장 잘 일치한 시간 차(초).

data.candidates[].reference_intrusion.window_start_secnumber

검사 구간 시작(초).

data.candidates[].reference_intrusion.window_end_secnumber

검사 구간 끝(초).

data.candidates[].reference_intrusion.matched_charactersinteger

일치한 글자 수.

data.candidates[].reference_intrusion.matched_charsinteger

일치한 글자 수.

data.candidates[].text_qa_statusstring

텍스트 검사 상태.

data.candidates[].active_start_msnumber

유효 음성 구간 시작(밀리초).

data.candidates[].active_end_msnumber

유효 음성 구간 끝(밀리초).

data.candidates[].tail_guard_attachedboolean

끝부분 확인용 보호 구간 부착 여부.

data.candidates[].tail_verifiedboolean

끝부분 검증 완료 여부.

data.candidates[].tail_verified_at_msnumber

끝부분을 검증한 시각(밀리초). 검증 전에는 null. null 허용.

data.candidates[].tail_body_end_at_msnumber

본문 끝 위치(밀리초). null 허용.

data.candidates[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록.

data.candidates[].generation_budget_exhaustedboolean

해당 발화의 자동 생성 시도 한도 소진 여부.

data.candidates[].retry_requires_new_regeneration_keyboolean

새 재생성 키가 필요한 상태인지 여부.

data.candidates[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다.

data.final_qualityobject

최종 결과 검사. 최종 검사 전에는 생략됩니다.

data.final_quality.schema_versionstring

품질 결과 규격 버전.

data.final_quality.attemptinteger

현재 검사 시도 회차.

data.final_quality.phasestring

현재 처리 단계.

data.final_quality.accepted_utterancesinteger

통과 발화 수.

data.final_quality.failed_utterancesinteger

실패 발화 수.

data.final_quality.total_utterancesinteger

전체 발화 수.

data.final_quality.expires_atstring

후보 결과 보관 만료 일시. null 허용.

data.final_quality.queue_elapsed_secnumber

대기 시간(초).

data.final_quality.generation_elapsed_secnumber

생성 시간(초).

data.final_quality.utterancesarray

발화별 검사 결과.

data.final_quality.utterances[].idstring

발화 식별자.

data.final_quality.utterances[].utterance_idstring

발화 식별자. 예: u001.

data.final_quality.utterances[].candidate_idstring

음성 후보 식별자.

data.final_quality.utterances[].statusstring

항목 처리 또는 검사 상태.

data.final_quality.utterances[].attemptinteger

생성 시도 회차.

data.final_quality.utterances[].voice_idstring

요청한 공개 목소리 ID.

data.final_quality.utterances[].created_atstring

항목 생성 일시.

data.final_quality.utterances[].elapsed_secnumber

처리 경과 시간(초).

data.final_quality.utterances[].reasonsarray

검사·실패 사유 목록. 사유가 없으면 빈 배열입니다.

data.final_quality.utterances[].speech_rateobject

발화 속도 검사. 검사 단계에 따라 일부 필드는 생략됩니다.

data.final_quality.utterances[].speech_rate.charactersinteger

발화 글자 수.

data.final_quality.utterances[].speech_rate.charsinteger

발화 글자 수.

data.final_quality.utterances[].speech_rate.duration_secnumber

측정 음성 길이(초).

data.final_quality.utterances[].speech_rate.duration_msnumber

측정 음성 길이(밀리초).

data.final_quality.utterances[].speech_rate.cpsnumber

초당 발화 글자 수.

data.final_quality.utterances[].speech_rate.expected_secnumber

예상 발화 길이(초).

data.final_quality.utterances[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초).

data.final_quality.utterances[].speech_rate.duration_rationumber

실제 길이/예상 길이 비율. 계산할 수 없으면 null. null 허용.

data.final_quality.utterances[].speech_rate.min_cpsnumber

최소 허용 초당 글자 수.

data.final_quality.utterances[].speech_rate.minimum_charactersinteger

검사에 필요한 최소 글자 수.

data.final_quality.utterances[].speech_rate.statusstring

속도 검사 결과.

data.final_quality.utterances[].audio_sha256string

후보 음원 SHA-256. 동일 음원 확인에 사용합니다.

data.final_quality.utterances[].audio_duration_msnumber

음원 길이(밀리초).

data.final_quality.utterances[].audio_availableboolean

후보 음원 다운로드 가능 여부.

data.final_quality.utterances[].transcriptstring

음원에서 인식한 텍스트.

data.final_quality.utterances[].cernumber

문자 오류율. 낮을수록 원문과 가깝습니다.

data.final_quality.utterances[].coveragenumber

원문에 대한 음성의 포함률.

data.final_quality.utterances[].repeatobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

data.final_quality.utterances[].repeat.detectedboolean

해당 현상이 검출됐는지 여부.

data.final_quality.utterances[].repeat.suspectedboolean

추가 확인이 필요한지 여부.

data.final_quality.utterances[].repeat.correlationnumber

비교 구간의 상관도.

data.final_quality.utterances[].repeat.best_lag_secnumber

가장 잘 일치한 시간 차(초).

data.final_quality.utterances[].repeat.window_start_secnumber

검사 구간 시작(초).

data.final_quality.utterances[].repeat.window_end_secnumber

검사 구간 끝(초).

data.final_quality.utterances[].repeat.matched_charactersinteger

일치한 글자 수.

data.final_quality.utterances[].repeat.matched_charsinteger

일치한 글자 수.

data.final_quality.utterances[].reference_intrusionobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

data.final_quality.utterances[].reference_intrusion.detectedboolean

해당 현상이 검출됐는지 여부.

data.final_quality.utterances[].reference_intrusion.suspectedboolean

추가 확인이 필요한지 여부.

data.final_quality.utterances[].reference_intrusion.correlationnumber

비교 구간의 상관도.

data.final_quality.utterances[].reference_intrusion.best_lag_secnumber

가장 잘 일치한 시간 차(초).

data.final_quality.utterances[].reference_intrusion.window_start_secnumber

검사 구간 시작(초).

data.final_quality.utterances[].reference_intrusion.window_end_secnumber

검사 구간 끝(초).

data.final_quality.utterances[].reference_intrusion.matched_charactersinteger

일치한 글자 수.

data.final_quality.utterances[].reference_intrusion.matched_charsinteger

일치한 글자 수.

data.final_quality.utterances[].text_qa_statusstring

텍스트 검사 상태.

data.final_quality.utterances[].active_start_msnumber

유효 음성 구간 시작(밀리초).

data.final_quality.utterances[].active_end_msnumber

유효 음성 구간 끝(밀리초).

data.final_quality.utterances[].tail_guard_attachedboolean

끝부분 확인용 보호 구간 부착 여부.

data.final_quality.utterances[].tail_verifiedboolean

끝부분 검증 완료 여부.

data.final_quality.utterances[].tail_verified_at_msnumber

끝부분을 검증한 시각(밀리초). 검증 전에는 null. null 허용.

data.final_quality.utterances[].tail_body_end_at_msnumber

본문 끝 위치(밀리초). null 허용.

data.final_quality.utterances[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록.

data.final_quality.utterances[].generation_budget_exhaustedboolean

해당 발화의 자동 생성 시도 한도 소진 여부.

data.final_quality.utterances[].retry_requires_new_regeneration_keyboolean

새 재생성 키가 필요한 상태인지 여부.

data.final_quality.utterances[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다.

data.final_quality.candidatesarray

음원 후보별 검사 결과.

data.final_quality.candidates[].idstring

발화 식별자.

data.final_quality.candidates[].utterance_idstring

발화 식별자. 예: u001.

data.final_quality.candidates[].candidate_idstring

음성 후보 식별자.

data.final_quality.candidates[].statusstring

항목 처리 또는 검사 상태.

data.final_quality.candidates[].attemptinteger

생성 시도 회차.

data.final_quality.candidates[].voice_idstring

요청한 공개 목소리 ID.

data.final_quality.candidates[].created_atstring

항목 생성 일시.

data.final_quality.candidates[].elapsed_secnumber

처리 경과 시간(초).

data.final_quality.candidates[].reasonsarray

검사·실패 사유 목록. 사유가 없으면 빈 배열입니다.

data.final_quality.candidates[].speech_rateobject

발화 속도 검사. 검사 단계에 따라 일부 필드는 생략됩니다.

data.final_quality.candidates[].speech_rate.charactersinteger

발화 글자 수.

data.final_quality.candidates[].speech_rate.charsinteger

발화 글자 수.

data.final_quality.candidates[].speech_rate.duration_secnumber

측정 음성 길이(초).

data.final_quality.candidates[].speech_rate.duration_msnumber

측정 음성 길이(밀리초).

data.final_quality.candidates[].speech_rate.cpsnumber

초당 발화 글자 수.

data.final_quality.candidates[].speech_rate.expected_secnumber

예상 발화 길이(초).

data.final_quality.candidates[].speech_rate.expected_duration_msnumber

예상 발화 길이(밀리초).

data.final_quality.candidates[].speech_rate.duration_rationumber

실제 길이/예상 길이 비율. 계산할 수 없으면 null. null 허용.

data.final_quality.candidates[].speech_rate.min_cpsnumber

최소 허용 초당 글자 수.

data.final_quality.candidates[].speech_rate.minimum_charactersinteger

검사에 필요한 최소 글자 수.

data.final_quality.candidates[].speech_rate.statusstring

속도 검사 결과.

data.final_quality.candidates[].audio_sha256string

후보 음원 SHA-256. 동일 음원 확인에 사용합니다.

data.final_quality.candidates[].audio_duration_msnumber

음원 길이(밀리초).

data.final_quality.candidates[].audio_availableboolean

후보 음원 다운로드 가능 여부.

data.final_quality.candidates[].transcriptstring

음원에서 인식한 텍스트.

data.final_quality.candidates[].cernumber

문자 오류율. 낮을수록 원문과 가깝습니다.

data.final_quality.candidates[].coveragenumber

원문에 대한 음성의 포함률.

data.final_quality.candidates[].repeatobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

data.final_quality.candidates[].repeat.detectedboolean

해당 현상이 검출됐는지 여부.

data.final_quality.candidates[].repeat.suspectedboolean

추가 확인이 필요한지 여부.

data.final_quality.candidates[].repeat.correlationnumber

비교 구간의 상관도.

data.final_quality.candidates[].repeat.best_lag_secnumber

가장 잘 일치한 시간 차(초).

data.final_quality.candidates[].repeat.window_start_secnumber

검사 구간 시작(초).

data.final_quality.candidates[].repeat.window_end_secnumber

검사 구간 끝(초).

data.final_quality.candidates[].repeat.matched_charactersinteger

일치한 글자 수.

data.final_quality.candidates[].repeat.matched_charsinteger

일치한 글자 수.

data.final_quality.candidates[].reference_intrusionobject

검출 결과. 분석할 수 없는 항목은 생략되거나 null입니다.

data.final_quality.candidates[].reference_intrusion.detectedboolean

해당 현상이 검출됐는지 여부.

data.final_quality.candidates[].reference_intrusion.suspectedboolean

추가 확인이 필요한지 여부.

data.final_quality.candidates[].reference_intrusion.correlationnumber

비교 구간의 상관도.

data.final_quality.candidates[].reference_intrusion.best_lag_secnumber

가장 잘 일치한 시간 차(초).

data.final_quality.candidates[].reference_intrusion.window_start_secnumber

검사 구간 시작(초).

data.final_quality.candidates[].reference_intrusion.window_end_secnumber

검사 구간 끝(초).

data.final_quality.candidates[].reference_intrusion.matched_charactersinteger

일치한 글자 수.

data.final_quality.candidates[].reference_intrusion.matched_charsinteger

일치한 글자 수.

data.final_quality.candidates[].text_qa_statusstring

텍스트 검사 상태.

data.final_quality.candidates[].active_start_msnumber

유효 음성 구간 시작(밀리초).

data.final_quality.candidates[].active_end_msnumber

유효 음성 구간 끝(밀리초).

data.final_quality.candidates[].tail_guard_attachedboolean

끝부분 확인용 보호 구간 부착 여부.

data.final_quality.candidates[].tail_verifiedboolean

끝부분 검증 완료 여부.

data.final_quality.candidates[].tail_verified_at_msnumber

끝부분을 검증한 시각(밀리초). 검증 전에는 null. null 허용.

data.final_quality.candidates[].tail_body_end_at_msnumber

본문 끝 위치(밀리초). null 허용.

data.final_quality.candidates[].tail_guard_attached_chunk_idsarray

보호 구간이 붙은 음성 구간 ID 목록.

data.final_quality.candidates[].generation_budget_exhaustedboolean

해당 발화의 자동 생성 시도 한도 소진 여부.

data.final_quality.candidates[].retry_requires_new_regeneration_keyboolean

새 재생성 키가 필요한 상태인지 여부.

data.final_quality.candidates[].candidate_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다.

data.final_quality.statusstring

최종 검사 상태.

data.final_quality.audio_sha256string

최종 음원 SHA-256.

apiobject

호출 메타데이터.

api.successboolean

API 공통 처리 여부. HTTP 상태·업무 결과와 함께 확인합니다.

api.costnumber

이번 호출에서 차감한 포인트. 무료 조회·재전송은 0.

api.pl_idinteger

과금 기록 ID. 과금 기록이 있을 때만 포함합니다.

정적 연동 예시입니다. 실제 계정·개인정보를 조회하지 않습니다.

결과 받기 예제직접 실행하지 않습니다GET /rest/tts/jobs/:job_id/candidates/:candidate_id/audio

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

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

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

const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/candidates/${encodeURIComponent(process.env.APICK_CANDIDATE_ID)}/audio`, {
  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.wav", new Uint8Array(await response.arrayBuffer()));

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

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/tts/jobs/{job_id}/candidates/{candidate_id}/audio".format(job_id=quote(os.environ["APICK_JOB_ID"], safe=""), candidate_id=quote(os.environ["APICK_CANDIDATE_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.wav", "wb") as output:
    for chunk in response.iter_content(65536):
        output.write(chunk)

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

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/candidates/' . rawurlencode(getenv('APICK_CANDIDATE_ID')) . '/audio');
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.wav', $body);

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

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

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

const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/candidates/${encodeURIComponent(process.env.APICK_CANDIDATE_ID)}/audio`, {
  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.wav", new Uint8Array(await response.arrayBuffer()));

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

import os
import requests
from urllib.parse import quote
response = requests.request("GET", "https://apick.app" + "/rest/tts/jobs/{job_id}/candidates/{candidate_id}/audio".format(job_id=quote(os.environ["APICK_JOB_ID"], safe=""), candidate_id=quote(os.environ["APICK_CANDIDATE_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.wav", "wb") as output:
    for chunk in response.iter_content(65536):
        output.write(chunk)

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

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/candidates/' . rawurlencode(getenv('APICK_CANDIDATE_ID')) . '/audio');
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.wav', $body);

7. 결과 받기

GET/rest/tts/jobs/:job_id/candidates/:candidate_id/audio

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

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

입력 항목

추가 폼 항목이 없습니다. 인증 헤더는 필요합니다.

응답과 성공 판정

HTTP 성공과 업무 결과를 구분하세요. 아래 서비스별 결과 필드가 실제 성공·실패를 나타냅니다.

파일 직접 응답

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

작업 재시도 예제직접 실행하지 않습니다POST /rest/tts/jobs/:job_id/retry

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

curl --fail-with-body --request POST "https://apick.app/rest/tts/jobs/${APICK_JOB_ID}/retry" \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'idempotency_key=apick-example-20260921-01' \
  --form-string 'utterance_ids[0]=u001'

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

const form = new FormData();
form.append("idempotency_key", "apick-example-20260921-01");
form.append("utterance_ids[0]", "u001");
const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/retry`, {
  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);

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

import os
import requests
from urllib.parse import quote
parts = [
    ("idempotency_key", (None, "apick-example-20260921-01")),
    ("utterance_ids[0]", (None, "u001")),
]
response = requests.request("POST", "https://apick.app" + "/rest/tts/jobs/{job_id}/retry".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]},
    files=parts,
    timeout=(10, 120))
response.raise_for_status()
result = response.json()
print(result)

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

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'idempotency_key' => 'apick-example-20260921-01',
    'utterance_ids[0]' => 'u001',
];
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/retry');
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);

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

curl --fail-with-body --request POST "https://apick.app/rest/tts/jobs/${APICK_JOB_ID}/retry" \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --connect-timeout 10 --max-time 120 \
  --form-string 'idempotency_key=apick-example-20260921-01' \
  --form-string 'utterance_ids[0]=u001'

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

const form = new FormData();
form.append("idempotency_key", "apick-example-20260921-01");
form.append("utterance_ids[0]", "u001");
const response = await fetch(`https://apick.app/rest/tts/jobs/${encodeURIComponent(process.env.APICK_JOB_ID)}/retry`, {
  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);

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

import os
import requests
from urllib.parse import quote
parts = [
    ("idempotency_key", (None, "apick-example-20260921-01")),
    ("utterance_ids[0]", (None, "u001")),
]
response = requests.request("POST", "https://apick.app" + "/rest/tts/jobs/{job_id}/retry".format(job_id=quote(os.environ["APICK_JOB_ID"], safe="")),
    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)

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

<?php
$headers = ["Authorization: Bearer " . getenv("APICK_API_KEY")];
$form = [
    'idempotency_key' => 'apick-example-20260921-01',
    'utterance_ids[0]' => 'u001',
];
$curl = curl_init('https://apick.app/rest/tts/jobs/' . rawurlencode(getenv('APICK_JOB_ID')) . '/retry');
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);

8. 작업 재시도

POST/rest/tts/jobs/:job_id/retry

Bearer 인증 · multipart/form-data · JSON 응답

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

입력 항목

폼 항목·타입

필수

설명·예제

idempotency_keystring

필수

동일 재개 요청에 재사용하는 키최대 길이: 128예: apick-example-20260921-01

utterance_ids[0]string

필수

재시도 API에서 다시 생성할 발화 ID. 예: u001. 접수 API에는 보내지 않습니다.예: u001

응답과 성공 판정

HTTP 성공과 업무 결과를 구분하세요. 아래 서비스별 결과 필드가 실제 성공·실패를 나타냅니다.

응답 상태

{
  "data": {
    "job_id": "7f7e43f578cd459db04696416435c789",
    "status": "cancelled"
  },
  "api": {
    "success": true,
    "cost": 0
  }
}

필드·타입

의미·조건

dataobject

아래 하위 항목을 확인하세요.

data.job_idstring

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

data.statusstring

작업 진행 상태. 완료 여부와 다운로드 가능 여부를 함께 확인합니다.허용값: waiting, processing, completed, cancelled, failed

data.resume_revisioninteger

재시도 회차. 0은 최초 생성이며 재시도할 때 증가합니다.

data.operation_revisioninteger

이번 재시도 요청이 시작한 회차. 현재 최대 회차와 다를 수 있습니다.

apiobject

호출 메타데이터.

api.successboolean

API 공통 처리 여부. HTTP 상태·업무 결과와 함께 확인합니다.

api.costnumber

이번 호출에서 차감한 포인트. 무료 조회·재전송은 0.

api.pl_idinteger

과금 기록 ID. 과금 기록이 있을 때만 포함합니다.

정적 연동 예시입니다. 실제 계정·개인정보를 조회하지 않습니다.

추가 입력 조건·전송 규칙

입력 상세

Header

이름

필수

설명

Authorization

Bearer 인증키

Content-Type

multipart/form-data; boundary는 클라이언트가 자동 설정합니다.

utterances[]에는 위 네 필드만 사용할 수 있습니다. 발화 식별자·화자·발화 종류·감정값은 서버가 생성·고정하므로 요청 필드가 아닙니다. 자유 감정 지시문, performance, SSML, 임의 속도·음높이, 문장 중간 무음 지시는 지원하지 않습니다.

{ "data": { "job_id": "7f7e43f578cd459db04696416435c789", "status": "waiting", "voice_id": "v2_ann_m_30s_01", "character_count": 27 }, "api": { "success": true, "cost": 10, "pl_id": 12345 } }

--form-string 'voice_id=v2_ann_m_30s_01' \ --form-string 'utterances[0][paragraph_id]=p004' \ --form-string 'utterances[0][pause_after]=normal' \ --form-string 'utterances[0][text]=그날 밤, 마을에는 이상할 만큼 고요한 정적이 내려앉았습니다. 하지만 한 집의 불빛만은 꺼지지 않았습니다.'