> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voicehire.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Lister les voix disponibles
> Retourne les voix utilisables pour le paramètre override_agent_id lors de la création ou modification d'une campagne
## Réponse
L'endpoint retourne deux groupes de voix :
* **`default_voices`** — voix VoiceHire par défaut, à utiliser via leur `agent_id`
* **`voice_clones`** — clones vocaux de votre agence (status `ready`), à utiliser via leur `voice_id`
```json theme={null}
{
"default_voices": [
{
"agent_id": "agent_xxx",
"voice_name": "Myriam",
"language": "fr",
"description": "Voix professionnelle française"
},
{
"agent_id": "agent_yyy",
"voice_name": "Susan",
"language": "en",
"description": "Professional English voice"
}
],
"voice_clones": [
{
"voice_id": "clone_zzz",
"voice_clone_name": "Mon clone perso",
"language": "fr",
"preview_audio_url": "https://.../preview.mp3"
}
]
}
```
Voix par défaut VoiceHire (toutes agences).
ID à passer dans `override_agent_id` lors de la création/modification de campagne
Nom de la voix
Code langue (`fr`, `en`, `es`)
Description courte de la voix
Clones vocaux de votre agence (status `ready` uniquement).
ID à passer dans `override_agent_id` lors de la création/modification de campagne
Nom du clone
Code langue (`fr`, `en`, `es`)
URL d'aperçu audio (mp3) du clone, si disponible
## Exemple de requête
```bash cURL theme={null}
curl -X GET https://app.voicehire.io/api/v1/voices \
-H "X-API-Key: vh_live_XXXXXXXXXXXXX"
```
```python Python theme={null}
import requests
response = requests.get(
"https://app.voicehire.io/api/v1/voices",
headers={"X-API-Key": "vh_live_XXXXXXXXXXXXX"}
)
voices = response.json()
print(f"{len(voices['default_voices'])} voix par défaut")
print(f"{len(voices['voice_clones'])} clone(s) d'agence")
# Exemple : choisir la première voix française
fr_voice = next((v for v in voices['default_voices'] if v['language'] == 'fr'), None)
if fr_voice:
print(f"Voix FR par défaut : {fr_voice['agent_id']}")
```
```javascript Node.js theme={null}
const axios = require('axios');
const response = await axios.get(
'https://app.voicehire.io/api/v1/voices',
{ headers: { 'X-API-Key': 'vh_live_XXXXXXXXXXXXX' } }
);
const { default_voices, voice_clones } = response.data;
console.log(`${default_voices.length} voix par défaut, ${voice_clones.length} clone(s)`);
```
## Notes importantes
* Pour utiliser une voix dans une campagne, passez son `agent_id` (voix par défaut) ou son `voice_id` (clone) dans le champ `override_agent_id` lors de la création (`POST /campaigns/create`) ou modification (`PATCH /campaigns/{campaign_id}`).
* Le drapeau `is_voice_clone` est déduit automatiquement côté backend, vous n'avez pas à le passer.
* Les clones d'agence apparaissent uniquement si leur status est `ready` (clonage terminé).
## Codes d'erreur
| Code | `code` | Description |
| ---- | ------------------------------------- | ----------------------------------------------- |
| 401 | `INVALID_API_KEY` / `MISSING_API_KEY` | Clé API manquante ou invalide |
| 500 | `INTERNAL_ERROR` | Erreur interne lors de la récupération des voix |
## OpenAPI
````yaml GET /api/v1/voices
openapi: 3.0.3
info:
title: VoiceHire API
description: >
API REST pour automatiser les campagnes de recrutement avec VoiceHire.
## Authentification
L'API utilise une authentification par clé API. Vous devez inclure votre clé
API dans l'en-tête `X-API-Key` de chaque requête.
```
X-API-Key: vh_live_XXXXXXXXXXXXX
```
## Format des réponses
Toutes les réponses sont au format JSON. Les erreurs suivent un format
standardisé :
```json
{
"error": {
"code": "ERROR_CODE",
"message": "Description de l'erreur",
"details": {}
}
}
```
## Limites
- Les numéros de téléphone doivent être des numéros français (06 ou 07)
- Maximum 100 candidats par requête d'ajout
- Les campagnes génèrent automatiquement 6 questions d'entretien
version: 1.0.0
contact:
name: Support VoiceHire
email: support@voicehire.io
url: https://www.voicehire.io
servers:
- url: https://app.voicehire.io
description: Production
- url: http://localhost:8080
description: Développement local
security:
- ApiKeyAuth: []
tags:
- name: Campagnes
description: Gestion des campagnes de recrutement
- name: Candidats
description: Gestion des candidats
- name: Compte
description: Informations du compte
paths:
/api/v1/voices:
get:
tags:
- Campagnes
summary: Lister les voix disponibles
description: >
Retourne les voix utilisables pour `override_agent_id` lors de la
création ou
modification d'une campagne. Deux groupes : les voix par défaut
VoiceHire
(utiliser `agent_id`) et les clones de l'agence (utiliser `voice_id`).
operationId: listVoices
responses:
'200':
description: Liste des voix
content:
application/json:
schema:
$ref: '#/components/schemas/VoicesListResponse'
example:
default_voices:
- agent_id: agent_xxx
voice_name: Myriam
language: fr
description: Voix professionnelle française
voice_clones:
- voice_id: clone_yyy
voice_clone_name: Mon clone perso
language: fr
preview_audio_url: https://.../preview.mp3
'401':
description: Non authentifié
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
VoicesListResponse:
type: object
properties:
default_voices:
type: array
description: Voix par défaut VoiceHire — à utiliser via `agent_id`
items:
$ref: '#/components/schemas/Voice'
voice_clones:
type: array
description: Clones de l'agence — à utiliser via `voice_id`
items:
$ref: '#/components/schemas/Voice'
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
description: Code d'erreur machine-readable
example: MISSING_API_KEY
message:
type: string
description: Message d'erreur human-readable
example: API key is required
details:
type: object
description: Détails supplémentaires sur l'erreur
additionalProperties: true
Voice:
type: object
properties:
agent_id:
type: string
description: >-
ID à utiliser dans `override_agent_id` (voix par défaut VoiceHire
uniquement)
example: agent_xxx
voice_id:
type: string
description: ID à utiliser dans `override_agent_id` (clones d'agence uniquement)
example: clone_yyy
voice_name:
type: string
description: Nom de la voix (présent pour les voix par défaut)
voice_clone_name:
type: string
description: Nom du clone (présent pour les clones d'agence)
language:
type: string
example: fr
description:
type: string
description: Description (présent pour les voix par défaut)
preview_audio_url:
type: string
format: uri
description: URL d'aperçu audio (présent pour les clones d'agence)
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Clé API au format vh_live_XXXXX
````