받아쓰기 — /v1/audio/transcriptions
소리를 글로. 오디오는 4MB 까지.
녹음 파일을 글로 바꿔드려요. 수업 녹음이나 회의록을 정리하실 때 쓰세요. 파일을 보내는 문이라 JSON 이 아니라 multipart 로 올리셔야 해요.
- 잡는 몫 — 부르기 전엔 길이를 몰라서, 미리 잡는 몫은 WAV(PCM)면 잰 길이, 그 밖의 파일은 1,000바이트를 1초로 어림해요 — 32kbps mp3 면 실제 길이의 4배, 64kbps 면 8배예요. 그래서 WAV 가 아니면 402 hold_exceeds_balance · 월 한도 429 는 재생 시간이 아니라 파일 크기로 재요 — 더 짧게 잘라 크기를 줄이면 풀려요. 끝나면 모델 회사가 알린 길이(gpt-4o 계열은 토큰)로 정산하고, 남은 몫은 돌아와요 — 정산은 잡은 몫을 넘지 않아요(2026-10-31 부터). 미리 잡을 때 gpt-4o 계열은 그 어림 길이를 1초에 소리 토큰 25개로, 출력은 그 절반으로 잡아요. prompt 를 실으면 gpt-4o 계열은 그 글의 바이트 수(UTF-8)만큼 글 토큰 몫도 더 잡아요. 예를 들어 64kbps 모노 mp3 3분(약 1.44MB)이면 1,440초 몫(gpt-transcribe 로 약 99 크레딧 · 10월 기준)을 잠깐 잡고, 끝나면 실제 180초 몫(약 12 크레딧)만 사용해요 — 잡는 몫이 8배일 뿐 쓰는 값은 실제 길이예요.
- AssemblyAI(universal-2)는 잡은 길이에서 받아쓰기를 멈춰요. 8kbps 보다 낮은 압축 파일이면 뒷부분이 빠진 채 200 으로 와요 — AssemblyAI 엔 WAV 로 보내거나 8kbps 이상으로 인코딩하세요.
- 한 번의 값 — 이 문 응답엔 글 문의 usage.cost_credits 가 없어요. 값은 응답 usage 로 셈해요. 초당 모델은 usage.seconds × GET /v1/models 의 seconds 단가예요(whisper-1 verbose_json 에 usage 가 없으면 최상위 duration 을 seconds 로 써요). gpt-4o 계열은 (usage.input_token_details.audio_tokens × input_audio + usage.input_token_details.text_tokens × input_text + usage.output_tokens × output 단가) ÷ 100만이에요(text_tokens 는 prompt 글 토큰이에요 — 칸이 없으면 0 으로 셈해요). AssemblyAI · ElevenLabs · CLOVA Speech 의 usage.seconds 는 저희가 이미 올린 청구 초라 다시 올리지 마세요.
- usage 는 json · verbose_json 으로 받았을 때만 와요. text · srt · vtt 응답엔 usage 가 없어 값을 셀 수 없으니, 값을 세려면 json 으로 받으세요.
curl https://oneport.kr/v1/audio/transcriptions \
-H "Authorization: Bearer $ONEPORT_API_KEY" \
-F model=whisper-1 \
-F file=@./lesson.m4a긴 녹음 나누기#
바이트로 자르지 말고 시간으로 잘라 주세요(예: ffmpeg -ss <시작> -t <길이>). 모노 64kbps mp3 는 1초에 8,000바이트라 4MB 에 약 8분이 들어가요 — 5분씩 자르면 넉넉해요(학교 지갑 학생 키는 더 짧게 — 아래 hold_exceeds_key_limit). 위 2분은 녹음 길이가 아니라 올리기 · 받아쓰기 · 답 받기를 모두 합친 처리 시간이에요 — 저희는 파일 크기(4MB)만 봐서, 4MB 에 드는 녹음은 한 번에 보내도 돼요. 처리가 2분을 넘으면 504 라(아래) 그땐 더 짧게 잘라요. 클라이언트 읽기 시간 제한은 2분보다 길게 두세요(까닭은 아래 끊김 문단). 시간 정보가 필요하면 whisper-1 에 response_format=verbose_json 을 주세요 — 벤더 답 그대로라 segments[].start · end · text 와 최상위 duration 이 OpenAI 문서와 같은 모양으로 와요. 각 조각 segments 의 start · end 에 그 조각의 시작 초를 더하면 원본 기준 시각이 돼요. 단어 시각이 필요하면 verbose_json 과 함께 timestamp_granularities[]=word 를 보내세요 — 저희는 그대로 넘겨요(words 는 벤더 답 그대로 · 벤더 동작). 시각(segments)을 저희가 확인한 모델은 whisper-1 뿐이라 srt · vtt 도 whisper-1 만 열어 뒀어요 — gpt-transcribe · gpt-4o-transcribe · gpt-4o-mini-transcribe 에 srt · vtt 를 보내면 지금은 400 이에요. whisper-1 은 2027-02-26 에 판매가 끝나요(줄의 retirement 칸 · 후속 gpt-transcribe). 다른 모델에 verbose_json 을 보내면 그대로 넘기지만, 벤더가 받는지는 확인하지 않았어요.
ffmpeg -i meeting.mp3 -ac 1 -b:a 64k -f segment -segment_time 300 part_%02d.mp3상태 코드로 돌아온 실패(4xx · 5xx)는 값이 안 나가서 다시 보내도 두 번 청구되지 않아요 — 상태 코드 없이 끊긴 건 실패가 아니에요(아래 끊김 문단). 벤더가 잠시 조이면 429 rate_limit_error, 벤더 쪽 일시 실패면 502 upstream_error, 벤더에 못 닿았거나 키 · 잔액을 잠깐 못 읽었으면 503 api_error 예요. 이 문의 422 는 모델 회사가 값을 거절한 것(type invalid_request_error)이라, 다시 보내지 말라는 422 upstream_execution_unconfirmed 와 달라요 — 문장대로 고쳐서 보내요. 402 held_by_others · 429 rate_limit_error · 502 upstream_error 엔 Retry-After 가 없어요. 503 api_error 는 모델 정보를 잠깐 못 읽었거나 저희 쪽 사정으로 모델 회사가 받지 않았을 때(error.reason provider_unavailable)만 Retry-After: 2 가 와요. 없으면 몇 초 쉬고(402 held_by_others 는 5초 · 503 은 2초쯤 — 다른 문이 Retry-After 로 주는 값이에요) 같은 조각을 그대로 다시 보내요(실패는 요금이 안 붙어요). 처리 시간을 넘기면 504 upstream_error 에 x-should-retry: false 가 와요. 값은 안 붙지만 같은 조각은 또 넘으니 더 짧게 잘라 보내세요(stream: true 는 이 문에서 안 받아요). 더 짧게 잘라야 풀리는 실패(위 504 · 413 · 아래 402 hold_exceeds_balance · 429 key_month_limit · group_budget)는 코드가 새로 자른 조각을 자동으로 보내도 돼요 — x-should-retry: false 는 504 와 한도 429 에만 붙어서, 413 은 상태로 · 402 는 error.reason 으로 가르세요. 이 문의 시간 초과는 504 하나예요 — 503 api_error 는 언제나 잠시 뒤 그대로 다시 보내면 돼요. 이 문의 502 · 504 엔 error.reason 이 없어요 — 상태와 type 으로 가르세요. 모델 회사로 보낸 뒤 실패한 받아쓰기(시간 초과 · 모델 회사 오류)는 요금이 안 붙지만, 정산 원장 CSV 에는 차감 0 인 줄로 남아 호출수 1 로 세요 — 그래서 실패가 있던 날은 호출수가 성공한 조각 수보다 커요. 초로 값을 매기는 모델(whisper-1 등)의 줄은 입력 · 출력토큰이 0 이고 길이(초)는 그 파일에 없어요 — 길이가 필요하면 응답 usage 를 기록해 두세요. 보내기 전에 막힌 실패(413 · 400 · 402 · 한도 429)는 줄이 안 남아요.
429 key_limit_exceeded · group_limit_exceeded 는 한도라 바로 다시 보내면 같아요(x-should-retry: false) — 다만 키 한도의 error.reason 이 "held_by_others" 면 같은 키로 아직 끝나지 않은 호출 몫 때문이라 x-should-retry: true · Retry-After: 5 가 붙어요 — 그만큼 기다렸다 같은 조각을 그대로 다시 보내요(「에러」 장). 키 한도의 다른 갈래는 "key_month_limit"(월 한도 · 이 파일 몫까지 더해 재서 남은 몫이 있어도 오니, 파일을 짧게 나누면 지나갈 수 있어요) · "key_day_limit"(하루 한도 · 이미 쓴 몫만 봐서 나눠도 같아요)예요. "hold_exceeds_key_limit" 은 학교 지갑 학생 API 키에서 이 파일 하나를 잡는 몫만으로 월 한도보다 큰 거예요(쓴 몫과 상관없이 · x-should-retry: false) — 잡는 몫은 WAV 가 아니면 파일 크기로 재서(위 「잡는 몫」) 학생 키 기본 월 한도(150 크레딧)엔 위 「5분씩」이 커요. whisper-1 · 64kbps mp3 면 5분 조각이 약 221 크레딧을 잡아 첫 조각부터 막히고, 3분 조각은 약 132 크레딧이라 지나가요(10월 기준). 월 한도는 이번 달 쓴 몫에 잡는 몫을 더해 재서(key_month_limit) 학생 키로 여러 조각을 보내려면 1분쯤(약 44 크레딧을 잡아요)으로 더 짧게 자르거나, 잰 길이로 잡는 WAV 로 보내세요. 강좌 몫은 "group_budget"(이 파일 몫까지 더해 재서, 파일을 짧게 나누면 지나갈 수 있어요) · "group_closed" · "group_not_started" · "group_ended"(나눠도 같아요 — 스페이스 관리자에게 말해 주세요)로 와요(「에러」 장). 402 insufficient_credit 도 error.reason 으로 갈래가 와요(글 문과 같은 자리라 openai SDK 면 Python e.body.get("reason") · Node err.error?.reason) — "held_by_others"(다른 호출이 잡아 둔 몫 · 잠시 뒤 그대로) · "hold_exceeds_balance"(이 파일 몫이 잔액보다 커요 — WAV 는 길이, 그 밖은 파일 크기로 재요 · 짧게 나누면 지나갈 수 있어요) · "below_minimum_balance"(충전). 403 model_not_in_plan(이 크레딧으로 못 부르는 모델)이나 스페이스에서 끈 모델의 403 도 키에 매인 거절이라 다른 조각을 보내도 같아요 — 그 자리에서 멈추세요. 스페이스 키면 space_content_policy 가 403 · 503 · 409 로 올 수 있고, 이 문은 error.code 에 이유가 와요 — unsupported_capability(403 · 그 스페이스는 전송 정책을 켜 두어 받아쓰기를 못 써요 — 스페이스 관리자에게 말해 주세요) · policy_unavailable(503 · 정책을 잠깐 못 읽었어요 — 잠시 뒤 다시) · policy_changed(409 · 부르는 사이 정책이 바뀌었어요 — 다시 보내면 바뀐 정책으로 봐요).
응답을 받기 전에 연결이 끊겨도 저희 쪽 받아쓰기는 끝까지 돌아요(길어야 2분). 손님이 끊어도 그 조각 값은 빠지니, 읽기 시간 제한은 2분보다 넉넉히 두세요. openai SDK 는 연결이 끊기면 같은 조각을 스스로 다시 보내니(SDK 동작) 이 문에선 Python max_retries=0 · Node maxRetries: 0 으로 두고 직접 가르세요. 정산은 답을 보낸 뒤 따로 돌아서, 차감이 늦게는 2분쯤 뒤에 보여요 — 끊기면 2분쯤 기다렸다가, 조각을 보내기 직전에 읽어 둔 GET /v1/credits 의 balance_credits 와 견줘 보세요. 그보다 일찍 보고 그대로라고 해서 실행되지 않은 게 아니에요. 줄었으면 그 조각은 이미 사용한 거예요. 같은 지갑을 다른 분도 쓰면 잔액엔 그분 사용도 섞이니, 그 키의 GET /v1/key 의 month.used_credits 도 보내기 전 값과 견줘 보세요. 잔액은 정수 크레딧(내림)이고 month.used_credits 는 올린 정수라, 1 크레딧이 안 되는 짧은 조각은 써도 두 값이 그대로일 수 있어요 — 그대로라는 것만으로 안 쓰였다고 보지 마세요. 이 문엔 끊긴 뒤 받아쓴 글을 되찾는 조회 길(Idempotency-Key · 상태 조회 주소)이 없어서, 같은 조각을 다시 보내면 한 번 더 사용해요 — 그래서 조각은 몇 분으로 작게 두세요(끊겨도 다시 보낼 몫이 작아요). balance_credits 는 잡아 둔 몫을 빼지 않은 잔액이에요 — 끊긴 요청이 도는 동안엔 그대로이고, 받아쓰기가 끝나 정산된 뒤에만 줄어요. 끊긴 요청이 아직 도는 동안에는 그 조각 몫이 잡혀 있어서, 잔액이 빠듯하면 곧바로 다시 보낸 요청이 402 일 수 있어요 — 2분 기다린 뒤 보내세요.
조각을 동시에 보내도 돼요 — 다만 조각마다 잡는 몫이 한꺼번에 잡혀서, 잔액이 그 합보다 적으면 늦게 간 조각이 402 held_by_others 예요(앞 조각이 끝나면 풀려요).
요청 파라미터#
요청 — multipart/form-data (JSON 아니에요)
| 파라미터 | 받는 값 | 저희가 하는 일 |
|---|---|---|
| file필수 | 오디오 파일 | 4,000,000바이트(4MB)까지예요. 넘으면 413 invalid_request_error 가 와요(다시 보내도 같아요) — 긴 녹음은 위처럼 시간으로 나눠서 보내주세요. OpenAI 모델엔 파일 형식을 거르지 않고 그대로 넘겨요 — 벤더가 못 읽으면 그 상태(400 · 415 등) 그대로 와요(아래 「벤더가 값을 거절하면」). |
| model필수 | 받아쓰기 모델 id | 다른 종류를 넣으시면 400 으로 어느 문인지 알려드려요. |
| language · prompt | 벤더 문서에 있는 값 | OpenAI 모델은 저희가 거르지 않고 그대로 넘겨요 — 벤더 문서를 그대로 보고 쓰시면 돼요. OpenAI 모델도 language 는 ISO 639-1 두 글자예요(예: ko · 벤더 동작). 용어집 같은 prompt 는 OpenAI 모델 어디에든 실어도 돼요. whisper-1 · gpt-transcribe 는 초로만 셈해서 prompt 몫이 따로 안 붙어요. gpt-4o-transcribe · gpt-4o-mini-transcribe 는 prompt 글을 토큰으로 세어 GET /v1/models 의 input_text 단가(소리 입력 input_audio 와 같은 값)로 셈해요(응답 usage.input_token_details.text_tokens). AssemblyAI(universal-2) · ElevenLabs(scribe_v2) · CLOVA Speech(clova-speech)는 file · model · language(ISO 639-1 두 글자) · response_format 만 받아요 — 다른 칸은 벤더에 보내기 전에 400 이에요. language 를 안 보내시면 AssemblyAI · ElevenLabs 는 말을 알아내고, clova-speech 는 한국어예요(ko · en · ja · zh 만). |
| response_format | json · verbose_json · diarized_json · text · srt · vtt(AssemblyAI · ElevenLabs · CLOVA Speech 모델은 json · text 만 — 다른 값은 보내기 전에 400) | 고르신 형식으로 돌려드려요. json · verbose_json · diarized_json 은 벤더 답 그대로예요 — OpenAI 모델의 json 은 whisper-1 · gpt-transcribe 면 {"text", "usage": {"type": "duration", "seconds"}}, gpt-4o 계열이면 usage 가 {"type": "tokens", "input_tokens", "input_token_details": {"audio_tokens", "text_tokens"}, "output_tokens", "total_tokens"} 예요(벤더 동작). 화자 구분은 지금 어느 모델로도 안 돼요 — diarized_json 은 OpenAI 모델엔 그대로 넘기지만 지금 목록의 OpenAI 모델은 화자 구분 모델이 아니에요(벤더가 거절하면 그 상태 그대로 · 값은 안 나가요). ElevenLabs · CLOVA Speech 는 저희가 화자 구분을 끄고 보내고, AssemblyAI 도 켜지 않아요 — 세 회사 모델에 diarized_json 을 보내면 벤더에 보내기 전에 400 이에요. text · srt · vtt 는 그 형식에 사용량이 안 실려서, 저희가 벤더엔 JSON 으로 받아 같은 글을 그 형식으로 옮겨 드려요. srt · vtt(자막)는 시간 정보를 주는 whisper-1 만 돼요 — 다른 모델이면 400 이에요. srt · vtt 는 저희가 verbose_json 의 segments 로 만들어서 조각마다 시각이 0초부터 시작해요 — 나눈 녹음을 자막 한 파일로 만들 땐 verbose_json 으로 받아 조각 시작 초를 더하세요. text · srt · vtt 에는 include · timestamp_granularities 를 같이 못 보내요(400). |
| stream | false | 아직 안 받아요. true 면 벤더에 보내기 전에 400 이에요 — 다 받아쓴 답을 한 번에 돌려드려요. |
AssemblyAI · ElevenLabs · CLOVA Speech 세 모델은 file · model · language · response_format(json · text)만 받아요. OpenAI 꼴 json({"text", "usage": {"type": "duration", "seconds"}})이나 text 로 돌려드려요 — 자막(srt · vtt) · verbose_json 은 whisper-1 을 써 주세요. clova-speech 는 WAV(PCM · fmt 하나 · data 하나가 파일 끝까지) 파일만 받아요(mp3 · m4a 는 400). 보내신 소리와 받아쓴 글은 저희가 저장하지 않고 사용량만 기록해요(「개요」 장). 받아쓴 직후 AssemblyAI · ElevenLabs 쪽 기록은 저희가 지워요. OpenAI 모델(whisper-1 · gpt-transcribe · gpt-4o 계열)은 저희가 따로 지우는 단계가 없어요 — 보관은 OpenAI API 정책을 따라요(벤더 동작). clova-speech 도 저희가 지우는 단계가 없어요 — 보관은 네이버클라우드 정책을 따라요(벤더 동작).
벤더가 값을 거절하면(400 · 413 · 415 · 422) 그 상태 그대로, type 은 invalid_request_error 로 벤더가 준 짧은 이유와 함께 돌려드려요(이 문의 422 는 벤더가 값을 거절한 것이지 upstream_execution_unconfirmed 가 아니에요) — 「잠시 후 다시」가 아니라 고쳐서 보내셔야 하는 경우예요. 값은 안 나가요.
이 문이 받는 모델#
표와 GET /v1/models 의 초당 값은 반올림한 값이에요(1 아래는 유효숫자 세 자리). 어림은 길이(초) × 초당 값으로 하세요(차감 값이에요 — 부를 때 잠깐 잡는 몫은 위 「요금 단위」대로 이보다 커서 잔액은 넉넉히 두세요) — 예를 들어 초당 0.092 크레딧(whisper-1 · 10월 기준)이면 90분(5,400초)에 약 497 크레딧이에요. 학생 말하기 1분이면 whisper-1 로 약 5.5 크레딧, gpt-transcribe(초당 0.069)로 약 4.1 크레딧이에요. 값은 바뀌니 정본은 GET /v1/models 예요 — 초당 모델은 pricing.rates 에 {"dimension": "seconds", "unit": "second", "credits": 0.092} 꼴 한 줄로, gpt-4o 계열 transcribe 는 input_audio · input_text · output 줄(100만 토큰당)로 와요. input_text 는 prompt 글 단가이고 input_audio 와 같은 값이에요. 이 두 모델엔 pricing.input_credits_per_mtok · output_credits_per_mtok 도 와요(input_text · output 줄과 같은 값). 코드에 값을 박지 말고 이 줄을 읽으세요.
받아쓰기
| 모델 | 차감 단가 |
|---|---|
| gpt-4o-transcribeGPT-4o Transcribe | 소리 입력 2,300 크레딧 / 1M 토큰 · 글 입력 2,300 크레딧 / 1M 토큰 · 출력 9,198 크레딧 / 1M 토큰 |
| gpt-4o-mini-transcribeGPT-4o mini Transcribe | 소리 입력 1,150 크레딧 / 1M 토큰 · 글 입력 1,150 크레딧 / 1M 토큰 · 출력 4,599 크레딧 / 1M 토큰 |
| whisper-1Whisper | 길이 0.092 크레딧 / 초 |
| gpt-transcribeGPT Transcribe | 길이 0.069 크레딧 / 초 |
| universal-2AssemblyAI Universal-2 | 길이 0.0383 크레딧 / 초 |
| scribe_v2ElevenLabs Scribe v2 | 길이 0.056 크레딧 / 초 |
| clova-speechCLOVA Speech | 길이 0.22 크레딧 / 초 |