읽어주기 — /v1/audio/speech
글을 소리로. 글자 수로 값이 정해집니다.
보내신 글을 음성 파일로 돌려드려요. 알림 문구를 읽어주거나 학습 자료에 소리를 붙일 때 쓰세요. 응답이 오디오 바이트라 --output 으로 파일에 받으시면 돼요. 이 문의 오류와 다시 보내기는 글 문 규칙(Idempotency-Key · 422 upstream_execution_unconfirmed · Retry-After)을 따르지 않아요 — 아래 「부르기 전에 값이 정해져요」와 「응답」을 보세요.
curl https://oneport.kr/v1/audio/speech \
-H "Authorization: Bearer $ONEPORT_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "model": "tts-1", "input": "오늘 급식은 김치찌개입니다.", "voice": "alloy" }' \
--output speech.mp3요청 파라미터#
요청 본문 (JSON)
| 파라미터 | 받는 값 | 저희가 하는 일 |
|---|---|---|
| model필수 | 읽어주기 모델 id | 다른 종류를 넣으시면 400 으로 어느 문인지 알려드려요. |
| input필수 | 문자열 | 한 번에 4,096자까지예요 — 넘으면 400 invalid_request_error 로 보내신 글자 수를 알려 드리고 값은 안 나가요. 더 긴 글은 나눠서 여러 번 부르세요 — 값은 글자 수에만 붙고 한 번 부를 때 붙는 기본값이 없어서 나눠도 더 붙지 않아요. 받은 소리를 하나로 잇는 건 받는 쪽에서 해요 — voice 는 한 번에 하나라 두 사람 대화도 줄마다 따로 불러 이어 붙여요. 잇기 쉬운 형식은 파일 머리(헤더)가 없는 response_format "pcm"(24kHz · 16비트 · 모노)이고, "wav" 는 받은 파일마다 머리가 붙어 있어요(둘 다 벤더 동작). 줄 사이 쉼은 받는 쪽에서 무음을 넣으면 돼요 — 무음엔 요금이 안 붙어요. 글자 수는 UTF-16 단위로 세요(JavaScript 의 text.length) — 한글 · 영문 · 공백 · 문장부호 · 줄바꿈은 1자, U+10000 위 글자(이모지 대부분)는 2자예요. Python 이면 sum(2 if ord(c) > 0xFFFF else 1 for c in s) 예요. 이 글자 수로 값이 정해지고, 응답 헤더 x-schoolorder-characters 에 저희가 센 글자 수가 담겨요. |
| voice · response_format · speed | 벤더 문서에 있는 값 | 저희가 거르지 않고 그대로 넘겨요 — 벤더 문서를 그대로 보고 쓰시면 돼요. 요금에는 영향이 없어요 — 요금은 글자 수로만 정해져서 느리게 읽혀도 같아요. |
머리글 이름의 schoolorder 는 예전 이름 그대로예요 — 원포트가 붙이는 머리글이 맞아요.
응답 헤더 — 저희가 붙이는 것
| 파라미터 | 받는 값 | 저희가 하는 일 |
|---|---|---|
| x-gateway-cost-credits | 소수(문자열) | 끝까지 받았을 때 이 호출에 쓰는 값이에요 — 다른 문 응답의 usage.cost_credits 와 같은 단위 · 같은 자예요(소수 넷째 자리까지 올린 값 · 0 보다 크면 적어도 0.0001 — 실제 차감은 올리기 전 값이라, 조각마다 받은 이 값을 더하면 실제보다 조각마다 0.0001 크레딧 안쪽으로 클 수 있어요). 소리가 오기 시작한 뒤 저희가 끊거나 벤더 흐름이 깨진 호출은 0크레딧이라 이 값과 달라요. |
| x-schoolorder-characters | 정수 | 값을 매길 때 저희가 센 글자 수예요. 청구가 이상하다 싶으면 이 둘을 같이 보시면 돼요. |
응답#
JSON 이 아니라 오디오 바이트가 그대로 와요. 다 만든 뒤에 한 번에 보내지 않고 만드는 대로 흘려보내서, 긴 글도 첫 소리가 빨리 와요. content-type 은 요청한 형식을 따르고(기본 audio/mpeg), 그래서 --output 으로 파일에 받으시면 돼요. 값·글자 수는 위 헤더 두 개로 확인하세요. 첫 소리는 60초 안에 와야 하고, 소리 사이가 60초 멎거나 부른 때부터 약 4분 30초가 되면 저희가 끊어요 — 손님 쪽 읽기 대기는 60초보다 길게 두세요(Python requests 면 timeout=(10, 120) 의 둘째 값 · 아래 예). 소리 사이 60초는 저희가 모델 회사에서 받는 간격이라 손님이 천천히 읽는 시간은 안 세요. 4분 30초는 부른 때부터 재는 시각이라 천천히 읽어도 다가와요 — 실시간으로 들려줄 때도 저희에게서는 끝까지 바로 받아 두고, 듣는 쪽엔 따로 흘려 주세요. 손님이 읽기를 멈춘 채 기한이 와도 저희가 끊어서 아래 「저희가 끊으면 0」이에요(2026-10-31 부터) — 다만 소리가 거기서 잘려요. 4,096자 한 번은 끝까지 받는 데 20초가 안 걸려서(10월 실측) 이 시계에 걸리지 않아요 — 긴 글은 4,096자 안에서 문장이 끝나는 곳으로 나눠 보내세요(조각이 짧아져도 값은 같아요). 소리가 오기 시작한 뒤(200) 저희가 끊거나 벤더 흐름이 중간에 깨지면 그 호출은 0크레딧이에요. content-length 는 안 실어요(만드는 대로 흘려보내서 길이를 미리 몰라요) — 끝까지 받았는지는 바이트 수가 아니라 읽기가 정상으로 끝났는지로 가려요. 끊긴 응답은 정상 끝 없이 연결이 끊겨 읽기가 오류로 끝나니, 받은 바이트를 완성본으로 쓰지 마세요. 손님 쪽에서 먼저 끊으면 소리가 오기 시작할 때 정한 값 그대로예요 — 손님 코드의 읽기 시간 초과 · 취소도 손님이 끊은 것이라 그 값을 사용해요. 손님 쪽 네트워크가 끊겨 연결이 닫혀도 손님이 끊은 것으로 쳐요 — 저희 쪽에선 손님이 취소한 것과 손님 쪽 네트워크가 끊긴 것을 가르지 못해요. 저희가 소리를 넘기기 시작하기 전에 끊기면 요금이 안 붙어요. 넘기기 시작한 뒤라면 손님 쪽에서 머리(200)를 아직 못 받았어도 손님이 끊은 것으로 쳐요 — 손님 쪽에선 200 을 못 받았다는 것만으로 요금이 없다고 가를 수 없어요(아래 「값이 나갔나」 ③). 요청 ID 는 다른 문처럼 200 을 포함한 모든 응답 머리글에 와요(request-id · 같은 값이 x-request-id · 오류면 몸통 error.request_id 에도 와요) — 소리를 읽기 전에 적어 두면, 끊긴 호출에 값이 나갔는지 그 값으로 물어보실 수 있어요. 잔액을 잡은 뒤의 호출은 저희 사용 기록에 같은 값이 남아 그 값으로 찾아요(2026-10-29 부터) — 문의하실 땐 요청 ID 와 부른 시각 · 모델 이름 · x-schoolorder-characters 값을 같이 admin@schoolorder.kr 로 알려 주세요. Idempotency-Key 는 받지 않아요(실어도 무시해요) — 같은 글을 두 번 사지 않으려면 끝까지 받은 파일을 받는 쪽에서 남겨 두고 다시 부르지 마세요. 오류 몸통은 글 문과 같은 꼴이라 Python openai SDK 에선 e.body 가 안쪽 {type, message, code, request_id} 예요(SDK 동작).
import os
import requests
BASE = "https://oneport.kr"
HEADERS = {"Authorization": f"Bearer {os.environ['ONEPORT_API_KEY']}"}
def speak(text, name):
r = requests.post(f"{BASE}/v1/audio/speech", headers=HEADERS,
json={"model": "tts-1", "input": text, "voice": "alloy"},
stream=True, timeout=(10, 120)) # 읽기 대기는 60초보다 길게
rid = r.headers.get("request-id") # 200 에도 와요 — 끊긴 호출을 물을 때 이 값이 필요해요
if r.status_code != 200:
err = r.json()["error"]
print("실패:", r.status_code, err["type"], err.get("reason"), rid)
return None
part = name + ".part"
try:
with open(part, "wb") as f:
for chunk in r.iter_content(chunk_size=65536):
f.write(chunk)
except requests.RequestException:
# 청크가 끝맺음 없이 끊기면 requests 는 ChunkedEncodingError · ConnectionError 를 내요(requests 동작).
os.remove(part)
print("받다가 끊겼어요 — 다시 받기 전에 요청 ID 를 적어 두세요:", rid)
return None
os.replace(part, name) # 읽기가 정상으로 끝났을 때만 완성본이에요
return nameimport { createWriteStream } from "node:fs";
import { rename, rm } from "node:fs/promises";
import { Readable } from "node:stream";
import { pipeline } from "node:stream/promises";
const res = await fetch("https://oneport.kr/v1/audio/speech", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.ONEPORT_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ model: "tts-1", input: "오늘 급식은 김치찌개입니다.", voice: "alloy" }),
});
const rid = res.headers.get("request-id"); // 200 에도 와요 — 끊긴 호출을 물을 때 이 값이 필요해요
if (!res.ok) {
const { error } = await res.json();
console.log("실패:", res.status, error.type, error.reason, rid);
} else {
try {
await pipeline(Readable.fromWeb(res.body as any), createWriteStream("speech.mp3.part"));
await rename("speech.mp3.part", "speech.mp3"); // 읽기가 정상으로 끝났을 때만 완성본이에요
} catch {
await rm("speech.mp3.part", { force: true });
console.log("받다가 끊겼어요 — 다시 받기 전에 요청 ID 를 적어 두세요:", rid);
}
}이 문이 받는 모델#
OpenAI 의 gpt-4o-mini-tts 는 안 팔아요 — 보내면 404 model_not_found 예요. tts-1 이나 tts-1-hd 를 쓰세요.
읽어주기
| 모델 | 차감 단가 |
|---|---|
| tts-1TTS 1 | 글자 13,797 크레딧 / 1M 글자 |
| tts-1-hdTTS 1 HD | 글자 27,594 크레딧 / 1M 글자 |
예를 들어 1,000자 지문 하나는 tts-1 로 약 14 크레딧, tts-1-hd 로 약 28 크레딧이에요 — 20개면 약 276 · 552 크레딧이에요(10월 기준 · 정본은 GET https://oneport.kr/v1/models 의 pricing). 1 크레딧은 2원(부가세 포함)이에요.
/v1/models 의 읽어주기 줄은 kind 가 "speech", endpoint 가 "POST /v1/audio/speech" 예요. pricing.rates 는 [{"dimension": "characters", "unit": "mchar", "unit_label": "1M characters", "credits": …}] 꼴이라 값은 글자 수 × credits ÷ 1,000,000 이에요. retirement 는 {"date": "2027-01-06", "successors": [ … ]} 꼴이에요 — successors 엔 벤더가 권하는 후속 모델 중 이 목록에 오른 id 만 와요(10월 기준 빈 배열이에요).