오디오 목소리 엔드포인트

오디오 목소리 엔드포인트 (Audio Voices Endpoints)

음성(voice) 관리를 위한 API입니다. 목소리 목록을 조회하고, 새 목소리를 만들고, 상세 정보·샘플 오디오를 가져오고, 삭제·수정하는 기능을 다룹니다.

출처: 문서

본문

TTS에 쓰는 목소리(voix)를 관리하는 엔드포인트 모음이에요. preset(기본 제공) 목소리와 custom(사용자 정의) 목소리를 모두 다룹니다.

GET /v1/audio/voices — List all voices (목소리 목록 조회)

목소리 목록을 가져옵니다. offset 페이지네이션은 더 이상 지원되지 않아서, 대신 GET /v2/audio/voices를 쓰세요.

쿼리 파라미터:

  • limit#integer — 반환할 최대 목소리 수.
  • offset#integer — 페이지네이션 오프셋.
  • type#"all"|"custom"|"preset" — 커스텀과 프리셋 중 필터링.

응답 필드 (200 Successful Response):

  • items#array<VoiceResponse> (필수) — 목소리 목록.
  • page#integer (필수)
  • page_size#integer (필수)
  • total#integer (필수)
  • total_pages#integer (필수)

TypeScript:

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

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

async function run() {
  const result = await mistral.audio.voices.list({});

  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.voices.list(limit=10, offset=0, type_="all")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/audio/voices \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "items": [
    {
      "created_at": "2025-12-17T10:25:07.818693Z",
      "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
      "name": "My resource",
      "type": "preset",
      "user_id": null
    }
  ],
  "page": "1",
  "page_size": "1000",
  "total": 56,
  "total_pages": "1"
}

POST /v1/audio/voices — Create a new voice (목소리 생성)

Base64로 인코딩된 오디오 샘플로 새 목소리를 만듭니다.

요청 본문:

  • name#string (필수) — 목소리 이름.
  • sample_audio#string (필수) — Base64 인코딩된 오디오 파일.
  • sample_filename#string|null — 확장자 감지를 위한 원본 파일명.
  • gender#string|null
  • age#integer|null
  • languages#array<string> — 지원 언어.
  • color#string|null
  • description#string|null
  • slug#string|null
  • tags#array<string>|null
  • retention_notice#integer — 기본값 30. 보관 기간 안내.

응답 필드 (200 Successful Response):

  • id#string (필수)
  • name#string (필수)
  • created_at#date-time (필수)
  • type#"preset"|"custom" (필수)
  • user_id#string|null (필수)
  • gender#string|null
  • age#integer|null
  • languages#array<string>
  • color#string|null
  • description#string|null
  • slug#string|null
  • tags#array<string>|null
  • trimmed_seconds#number|null
  • retention_notice#integer — 기본값 30.

TypeScript:

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

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

async function run() {
  const result = await mistral.audio.voices.create({
    name: "<value>",
    sampleAudio: "<value>",
  });

  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.voices.create(name="<value>", sample_audio="<value>", retention_notice=30)

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/audio/voices \
 -X POST \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{
  "name": "My voice",
  "sample_audio": "base64-encoded-audio-data"
}'

응답 예시 (200):

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "name": "My resource",
  "type": "preset",
  "user_id": null
}

GET /v1/audio/voices/{voice_id} — Get voice details (목소리 상세 조회)

특정 목소리의 상세 정보(샘플 제외)를 가져옵니다.

경로 파라미터:

  • voice_id#string (필수)

응답 필드 (200 Successful Response): 생성 응답과 동일한 VoiceResponse 필드 목록입니다.

TypeScript:

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

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

async function run() {
  const result = await mistral.audio.voices.get({
    voiceId: "<id>",
  });

  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.voices.get(voice_id="<id>")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/audio/voices/{voice_id} \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "name": "My resource",
  "type": "preset",
  "user_id": null
}

DELETE /v1/audio/voices/{voice_id} — Delete a custom voice (커스텀 목소리 삭제)

커스텀 목소리를 삭제합니다.

경로 파라미터:

  • voice_id#string (필수)

응답 필드 (200 Successful Response): VoiceResponse 필드 목록.

TypeScript:

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

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

async function run() {
  const result = await mistral.audio.voices.delete({
    voiceId: "f42bf0d7-8a10-4b98-bbfa-589a232209d2",
  });

  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.voices.delete(voice_id="f42bf0d7-8a10-4b98-bbfa-589a232209d2")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/audio/voices/{voice_id} \
 -X DELETE \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json'

응답 예시 (200):

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "name": "My resource",
  "type": "preset",
  "user_id": null
}

PATCH /v1/audio/voices/{voice_id} — Update voice metadata (목소리 메타데이터 수정)

목소리의 메타데이터(이름, 성별, 언어, 나이, 태그)를 부분 수정합니다.

경로 파라미터:

  • voice_id#string (필수)

요청 본문: 부분 수정용 요청 모델.

  • name#string|null
  • gender#string|null
  • languages#array<string>|null
  • age#integer|null
  • tags#array<string>|null
  • description#string|null

응답 필드 (200 Successful Response): VoiceResponse 필드 목록.

TypeScript:

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

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

async function run() {
  const result = await mistral.audio.voices.update({
    voiceId: "030a6b20-e287-414d-9a77-6b76a4a56c9d",
    voiceUpdateRequest: {},
  });

  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.voices.update(voice_id="030a6b20-e287-414d-9a77-6b76a4a56c9d")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/audio/voices/{voice_id} \
 -X PATCH \
 -H 'Authorization: Bearer ***' \
 -H 'Content-Type: application/json' \
 -d '{}'

응답 예시 (200):

{
  "created_at": "2025-12-17T10:25:07.818693Z",
  "id": "019b2bd7-96e7-7219-8c0b-45a73da50088",
  "name": "My resource",
  "type": "preset",
  "user_id": null
}

GET /v1/audio/voices/{voice_id}/sample — Get voice sample audio (목소리 샘플 오디오)

특정 목소리의 샘플 오디오를 가져옵니다.

경로 파라미터:

  • voice_id#string (필수)

응답 (200): 타입 binary — 오디오 바이너리 데이터.

TypeScript:

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

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

async function run() {
  const result = await mistral.audio.voices.getSampleAudio({
    voiceId: "<id>",
  });

  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.voices.get_sample_audio(voice_id="<id>")

    # Handle response
    print(res)

curl:

curl https://api.mistral.ai/v1/audio/voices/{voice_id}/sample \
 -X GET \
 -H 'Authorization: Bearer ***'

응답 예시 (200):

"base64-encoded-data"

더 알아보기 (Learn more)