오디오 전사 엔드포인트

오디오 전사 엔드포인트 (Audio Transcriptions Endpoints)

오디오를 텍스트로 변환(전사, transcription)하는 API입니다. 일반 전사와 SSE 스트리밍 전사 두 가지 방식을 지원해요.

출처: 문서

본문

음성 파일을 텍스트로 바꿔주는 엔드포인트예요. voxtral-mini-latest 같은 모델에 오디오를 넘기면 전사된 문장이 나옵니다.

POST /v1/audio/transcriptions — Create Transcription (전사 생성)

오디오 파일을 텍스트로 변환합니다.

요청 본문 (multipart/form-data):

  • file#File — 업로드할 파일. 파일명을 바꾸고 싶으면 file=@path/to/your/file.jsonl;filename=custom_name.jsonl 형태로, 그냥 쓰면 file=@path/to/your/file.jsonl 형태로 보내면 돼요.
  • file_id#string|null — /v1/files에 미리 업로드한 파일의 ID.
  • file_url#string|null — 전사할 파일의 URL.
  • model#string (필수) — 사용할 모델의 ID.
  • language#string|null — 오디오 언어 (예: 'en'). 언어를 지정하면 정확도가 올라가요.
  • diarize#boolean — 기본값 false. 화자 분리 여부.
  • timestamp_granularities#array<"segment"|"word"> — 응답에 포함할 타임스탬프 단위.
  • temperature#number|null — 샘플링 온도.
  • stream#boolean — 기본값 false.
  • context_bias#array<string> — 맥락 편향 단어 목록.

응답 필드 (200 Successful Response):

  • text#string (필수) — 전사된 텍스트.
  • language#string|null (필수)
  • model#string (필수)
  • segments#array<TranscriptionSegmentChunk> — 세그먼트 단위 결과.
  • usage#UsageInfo (필수) — 토큰 사용량.

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.audio.transcriptions.complete({
    model: "voxtral-mini-latest",
  });

  console.log(result);
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.audio.transcriptions.complete(model="voxtral-mini-latest", diarize=False)

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/audio/transcriptions \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "model": "voxtral-mini-latest"
}'

응답 예시 (200): (아래 text 값은 전사된 샘플 문장 일부를 생략한 것으로, 실제 응답에는 전체 전사가 들어갑니다)

{
  "model": "voxtral-mini-2507",
  "text": "This week, I traveled to Chicago to deliver my final farewell address ... ",
  "language": "en",
  "segments": [],
  "usage": {
    "prompt_audio_seconds": 203,
    "prompt_tokens": 4,
    "total_tokens": 3264,
    "completion_tokens": 635
  }
}

POST /v1/audio/transcriptions#stream — Create Streaming Transcription (SSE)

SSE 방식으로 전사 결과를 스트리밍합니다.

요청 본문 (multipart/form-data): 일반 전사와 동일한 필드들이며, stream의 기본값이 true예요.

  • file#File — 업로드할 파일.
  • file_id#string|null — /v1/files에 업로드한 파일의 ID.
  • file_url#string|null — 전사할 파일의 URL.
  • model#string (필수)
  • language#string|null — 오디오 언어 (예: 'en').
  • diarize#boolean — 기본값 false.
  • timestamp_granularities#array<"segment"|"word">
  • temperature#number|null
  • stream#boolean — 기본값 true.

응답 (200): 타입 event-stream<TranscriptionStreamEvents> — 전사 이벤트 스트림.

  • TranscriptionStreamEvents — {object}

TypeScript:

import { Mistral } from "@mistralai/mistralai";

const mistral = new Mistral({
  apiKey: proces...EY"] ?? "",
});

async function run() {
  const result = await mistral.audio.transcriptions.stream({
    model: "Camry",
  });

  for await (const event of result) {
    console.log(event);
  }
}

run();

Python:

from mistralai.client import Mistral
import os

with Mistral(
    api_key=os.getenv("MISTRAL_API_KEY", ""),
) as mistral:

    res = mistral.audio.transcriptions.stream(model="Camry", diarize=False)

    with res as event_stream:
        for event in event_stream:
            # handle event
            print(event, flush=True)

curl:

curl https://api.mistral.ai/v1/audio/transcriptions#stream \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "model": "voxtral-mini-latest"
}'

더 알아보기 (Learn more)