서버나 스크립트에서 영상 링크 보내기
API 키와 영상 URL로 POST 요청을 보내세요. Python을 비롯해 HTTP 요청을 보낼 수 있는 환경이면 돼요. wait=60을 붙이면 최대 60초 동안 기다려요. 요청 필드는 API 문서에서 확인하세요.
대시보드에서 API 키를 만들고 서버나 스크립트에서 사용하세요. 요청이 성공하면 바로 변환 ID를 저장하세요. 기다리는 시간이 끝났다고 변환까지 실패한 건 아니에요. 같은 영상을 다시 보내지 말고 GET /v1/transcriptions/:id로 확인하세요.
처리 중에는 queued, fetching, transcribing 상태를 볼 수 있어요. completed면 스크립트를 읽고, failed면 오류를 처리하세요. 네트워크 지연이나 영상 접근 오류를 빈 스크립트로 처리하지 않도록 상태를 구분해 두세요.
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-H "Content-Type: application/json" \
-d '{"platform":"youtube","url":"https://youtu.be/dQw4w9WgXcQ"}'transcript_source로 자막과 AI 구분하기
자막에서 가져온 스크립트에는 자막 종류도 함께 담겨요. billed_minutes는 영상 길이를 분 단위로 올림한 값이에요. 전체 필드는 응답 객체 문서에서 확인하세요.
출처가 중요한 앱이라면 transcript_source와 caption_kind를 함께 저장하세요. 업로더가 올린 자막은 원문을 유지하고 단어별 타임스탬프는 없어요. 자동 생성 자막에는 단어 시작 시간이, AI 텍스트 변환에는 단어 시작·종료 시간과 신뢰도가 있어요.
segments에는 각 구간의 시작과 끝이 초 단위로 들어 있어요. 재생 위치로 이동하거나 메모에 근거를 붙일 때 쓰세요. 단어별 정보가 필요한 화면에서만 include=words를 추가하면 돼요. 아래 JSON은 구조를 설명하는 예시로, 예제 영상의 실제 발언은 아니에요.
{
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"status": "completed",
"transcript_source": "youtube_captions",
"caption_kind": "auto_generated",
"language": "en",
"billed_minutes": 4,
"transcript": {
"text": "Welcome back to the channel. Today we are looking at how transcripts are made.",
"segments": [
{ "start": 0, "end": 4.2, "speaker": null, "language": "en", "text": "Welcome back to the channel." }
]
}
}자막 원문이 필요한지, 음성 변환이 필요한지
source의 기본값은 auto예요. captions(자막만)을 고르면 쓸 수 있는 자막이 없을 때 no_captions로 끝나고 크레딧은 차감하지 않아요. stt는 항상 음성으로 변환해요. 조합별 동작은 source 옵션 문서를 확인하세요.
게시된 자막 원문이 꼭 필요하면 captions를, 음성을 새로 변환하거나 화자를 나누려면 stt를 고르세요. auto에 diarize=true를 더하면 자막이 있어도 음성으로 변환해요. captions와 화자 분리를 함께 요청하면 오류가 나요. 화자 옵션을 임의로 무시하지 않아요.
language를 지정하면 그 언어에 맞는 자막을 찾아요. auto에서는 영상의 원래 언어를 기준으로 골라요. 자동 번역 자막은 사용하지 않아요. 음성 변환에 언어 힌트를 줘도 다른 언어로 번역해 주는 건 아니에요.
{
"platform": "youtube",
"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"source": "stt"
}다시 보내기 전에 오류와 기존 작업 확인하기
먼저 오류 코드를 확인하세요. 비공개·연령 제한 영상이나 진행 중인 라이브는 같은 요청을 반복해도 해결되지 않아요. no_captions라면 음성 변환을 써도 되는지 결정하세요. 아직 처리 중이라면 저장한 ID로 상태를 다시 읽으세요.
생성 요청을 재시도할 때는 Idempotency-Key 규칙을 따르세요. 최근 스크립트 재사용은 별도 옵션으로, 같은 영상과 같은 옵션을 보낸 이전 요청을 찾아요. 캐시에서 가져왔어도 새 작업이면 과금할 수 있어요. 완료된 작업을 ID로 다시 읽는 데는 크레딧이 들지 않아요.
같은 생성 API로 TikTok, Instagram 등 지원하는 영상 링크도 보낼 수 있어요. YouTube, X, TikTok, Bluesky에서는 쓸 수 있는 자막이 없으면 음성으로 변환해요. 플랫폼마다 가능한 조합이 다르니 입력 화면을 만들 때 지원 소스와 옵션을 확인하세요.