지원 링크와 변환 옵션

YouTube, X, TikTok, Instagram, Facebook, Bluesky의 영상 링크나 오디오·영상 파일로 변환 작업을 시작할 수 있어요. 그 밖에 지원하는 공개 녹화 영상과 URL 형식도 아래에서 확인하세요. 자막을 가져올지 음성을 변환할지는 source, 화자 분리는 diarize, 언어는 language로 설정해요. POST /v1/transcriptions의 본문에 넣는 필드이며, 모두 생략할 수 있어요.

지원 플랫폼

url에 영상 링크를 넣으면 API가 플랫폼을 알아내요. platform을 직접 지정할 수도 있지만, 링크의 플랫폼과 같아야 해요.

Twitch부터 Snapchat Spotlight까지 추가된 다섯 플랫폼에서는 HTTPS 링크만 받아요. URL에 인증 정보를 넣거나 별도 포트를 지정하면 안 돼요. 공개된 개별 녹화 영상만 가능하며 비공개·로그인 필수 게시물, 라이브·처리 중인 방송, 프로필, 피드, 컬렉션은 지원하지 않아요. 계정 쿠키도 보내지 않아요.

URL에 재생 시간을 넣어도 해당 구간만 잘라서 처리하지는 않아요. Twitch 클립과 Snapchat Spotlight의 media_id는 내부 형식을 알 수 없는 문자열일 수 있어요. URL에서 ID를 추측하지 말고 반환받은 값을 그대로 보관하세요.

X, TikTok, Instagram, Facebook, Bluesky에서도 공개 게시물만 사용할 수 있어요. 영상이 여러 개면 첫 번째 영상만 변환해요. 프로필, 스토리, 라이브 페이지, TikTok 사진 게시물은 대상이 아니에요. 로그인이 필요하면 login_required, 오디오 트랙이 없으면 no_audio로 작업이 실패해요. 어느 경우에도 크레딧을 차감하지 않아요.

YouTube, X, TikTok, Bluesky, Dailymotion, LinkedIn에서는 영상 원본 언어의 자막을 가져올 수 있어요. 실제로 사용할 수 있는 자막이 있는지는 영상마다 달라요. Instagram, Facebook, Twitch, Pinterest, Snapchat은 auto나 stt로 AI 음성 텍스트 변환(STT)을 사용하며, captions는 허용하지 않아요. 플랫폼이나 파일 업로드에 관계없이 실제로 측정한 길이에 같은 분당 요금을 적용해요.

단축 링크는 표에 있는 형식만 지원해요. 제출 시점에 게시물 ID를 알 수 없는 소셜 공유 링크는 이전 변환 작업과 연결할 수 없어요. 기존 스크립트를 재사용하려면 전체 게시물 링크를 보내세요.

YouTube 링크 형식

YouTube 영상 주소는 url에 넣으세요. platform은 생략해도 되고 youtube로 지정해도 돼요. 아래 형식을 지원하며 www.는 있어도 없어도 돼요.

t, list, si 같은 추가 쿼리 파라미터는 처리에 영향을 주지 않아요. 주소 형식이 달라도 같은 영상이면 하나의 영상으로 인식해요. 반드시 전체 URL을 보내세요. 11자리 영상 ID만 보내거나 채널·재생목록 전용 주소 등 지원하지 않는 링크를 보내면 422 invalid_url을 반환해요. 지원하지 않는 platform 값에는 422 unsupported_platform과 supported_platforms 목록을 반환해요.

영상 공개 범위는 공개 또는 일부 공개여야 해요. 비공개 영상은 media_private, 연령 제한 영상은 age_restricted, 진행 중인 라이브는 live_stream으로 실패해요. 보유한 파일을 변환하려면 파일 업로드를 이용하세요.

source

source로 기존 자막을 가져올지, 음성을 AI로 변환할지 선택하세요.

파일 업로드는 항상 음성 텍스트 변환(STT)을 사용해요. source에는 auto나 stt를 넣으세요. captions를 보내면 422 invalid_request를 반환해요.

자막은 요청한 언어와 맞아야 사용할 수 있어요. language가 auto이면 영상 원본 언어를 기준으로 골라요. YouTube에서는 업로더가 올린 자막이나 YouTube가 해당 언어로 자동 생성한 자막을 사용해요. 자동 번역 자막은 사용하지 않아요. 업로더가 올린 자막, 출처를 알 수 없는 자막, 자동 생성 자막 순으로 선택해요. 출처를 모르는 자막을 업로더가 올린 것으로 간주하면 안 돼요.

X에서는 제공되는 VTT 트랙을 사용해요. 자동 생성 자막도 세그먼트별 타임스탬프만 있으며 단어별 타임스탬프는 없어요. auto에서 자막을 사용할 수 없거나 내용을 파싱하지 못하면 STT로 전환할 수 있어요. 라우팅, 저장소, 코드 오류를 STT 전환으로 처리하지는 않아요. stt를 지정하면 처음부터 자막을 확인하지 않아요.

diarize

누가 말하는지 구분하려면 diarize를 켜세요. 기본값은 false예요.

• 화자 분리는 음성 텍스트 변환(STT)에서만 가능해요. source가 auto여도 diarize: true를 넣으면 자막 대신 바로 음성을 변환해요.
• source: "captions"와 diarize: true는 함께 쓸 수 없어요. 두 값을 같이 보내면 422 invalid_request를 반환해요.
• 화자는 Speaker 1, Speaker 2처럼 표시해요. transcript.speakers와 각 세그먼트의 speaker 필드에서 확인할 수 있어요. text, srt에서는 문장 앞에 Speaker 1: 을 붙이고, vtt에서는 <v Speaker 1> 화자 태그를 사용해요.

{ "platform": "youtube", "url": "https://youtu.be/dQw4w9WgXcQ", "source": "stt", "diarize": true }

language

language에는 기본값인 auto를 쓰거나 en, de, es처럼 두 글자 ISO 639-1 언어 코드를 넣으세요.

• 자막을 가져올 때는 이 값으로 트랙의 언어를 골라요. auto이면 영상 원본 언어를 사용해요.
• 음성 텍스트 변환(STT)에서는 STT 제공자가 참고할 언어 힌트로 보내요. auto이면 언어를 자동 감지해요. 각 세그먼트의 language에는 해당 구간의 언어가 들어가요.

작업 객체의 language에는 영상에서 주로 사용하는 언어가 들어가요.

스크립트 출처와 응답 데이터

스크립트의 출처는 transcript_source로 확인하세요. youtube_captions, x_captions, tiktok_captions, bluesky_captions, dailymotion_captions, linkedin_captions, speech_to_text 중 하나예요. 자막 종류를 나타내는 caption_kind는 manual, auto_generated 또는 출처를 알 수 없다는 뜻의 null이에요. null인 자막을 업로더가 올린 자막으로 표시하지 마세요.

YouTube 자막은 [Music] 같은 태그까지 원문 그대로 가져와요. 음성 텍스트 변환(STT)은 최대 5시간까지 처리해요. 이보다 길면 media_too_long으로 실패해요.

X(x_captions), TikTok, Bluesky, Dailymotion, LinkedIn 자막의 타임스탬프는 세그먼트 단위예요. 자동 생성 자막도 include=words로 조회하면 세그먼트마다 words: null이 나오고, 화자 분리도 지원하지 않아요. AI로 단어별 타임스탬프를 만들려면 source: "stt"를 지정하세요. 화자 분리는 auto나 stt에 diarize: true를 함께 넣으면 돼요.

사용 요금

자막을 가져오든 음성 텍스트 변환(STT)을 하든 요금은 같아요. 미디어 길이를 분 단위로 올림해 1분당 1크레딧을 차감해요. 변환 방식을 바꿔도 분당 요금은 달라지지 않아요. 자세한 내용은 요금제와 사용 한도를 확인하세요.