---
title: "Hear voice samples of a variant"
method: POST
path: "/v1/mascots/{id}/variants/{variantId}/voice/samples"
tags: ["Voice"]
---

# Hear voice samples of a variant

`POST /v1/mascots/{id}/variants/{variantId}/voice/samples`

## Request

- Base URL: `https://api.masko.ai`
- URL: `https://api.masko.ai/v1/mascots/{id}/variants/{variantId}/voice/samples`
- Auth: HTTP bearer

Designs three voices from a description, each reading the same line. Costs 1 credit for the three. Keep one with PUT /v1/mascots/{id}/variants/{variantId}/voice within 24 hours.

## Path parameters

- `id` string, uuid, required
- `variantId` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- VoiceSamplesBody
  - `description` string, required: How the voice sounds: age, pitch, pace, energy, texture, mood and accent.
  - `sample_line` string: The line the samples read. Lines shorter than 100 characters are extended. Omit it for a line in the mascot's name.

## Response `201`

Three samples

- object
  - `data` VoiceSamples, required
    - `samples` object[], required
      - `id` string, uuid, required: Pass it to PUT .../voice to keep this voice.
      - `url` string, uri, required
      - `duration` number, nullable, required
    - `sample_line` string, required
    - `cost_credits` number, required
    - `expires_at` string, required: Samples not kept by then can no longer be kept.

## Other responses

- `400`: Invalid request
- `401`: Authentication required
- `402`: Not enough credits
- `403`: The key lacks permission, or the voice belongs to the Marketplace creator
- `404`: Mascot, variant or sample not found
- `409`: The variant is not approved yet, or the sample expired
- `429`: Too many voice requests; retry later
- `502`: Masko could not write the ideas or the adjustment; retry
- `503`: The voice service is unavailable; retry later

---

[API](https://skmtc.dev/masko/apis/masko-api.md) · [All operations](https://skmtc.dev/masko/apis/masko-api/llms.txt) · [OpenAPI document](https://skmtc.dev/masko/apis/masko-api/revisions/84832e255613?raw)