본문으로 건너뛰기
원포트 AI

읽어주기 — /v1/audio/speech

글을 소리로. 글자 수로 값이 정해집니다.

AI 에게 넘기기ChatGPT 에서 열기 (새 창)Claude 에서 열기 (새 창)원문 열기

보내신 글을 음성 파일로 돌려드려요. 알림 문구를 읽어주거나 학습 자료에 소리를 붙일 때 쓰세요. 응답이 오디오 바이트라 --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 동작).

Python — 끝까지 받았을 때만 파일로 · 요청 ID 적어 두기
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 name
Node — 같은 일
import { 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월 기준 빈 배열이에요).