curl --request POST 'https://api.voicecheap.ai/v1/actions/tts_align' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","historyId":"722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"}'
const input = {
requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
historyId: '722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/tts_align', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/tts_align",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"status": "running",
"pollAction": "action_request_get",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"status": "ready",
"wordAlignment": [
{
"text": "Hello",
"startSeconds": 0,
"endSeconds": 0.6,
"sourceStartCharacterIndex": 0,
"sourceEndCharacterIndex": 5
},
{
"text": "world.",
"startSeconds": 0.7,
"endSeconds": 1.4,
"sourceStartCharacterIndex": 6,
"sourceEndCharacterIndex": 12
}
]
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "tts_align",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "tts_align",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
Sintesi vocale
Allinea le parole della voce generata
Prepara o recupera le indicazioni temporali delle parole per una creazione vocale di tua proprietà. Restituisce ready, processing o unavailable. L’allineamento completato viene memorizzato nella cache.
POST
/
v1
/
actions
/
tts_align
curl --request POST 'https://api.voicecheap.ai/v1/actions/tts_align' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","historyId":"722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"}'
const input = {
requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
historyId: '722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/tts_align', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/tts_align",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"status": "running",
"pollAction": "action_request_get",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"status": "ready",
"wordAlignment": [
{
"text": "Hello",
"startSeconds": 0,
"endSeconds": 0.6,
"sourceStartCharacterIndex": 0,
"sourceEndCharacterIndex": 5
},
{
"text": "world.",
"startSeconds": 0.7,
"endSeconds": 1.4,
"sourceStartCharacterIndex": 6,
"sourceEndCharacterIndex": 12
}
]
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "tts_align",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "tts_align",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
Prepara o recupera le indicazioni temporali delle parole per una creazione vocale di tua proprietà. Restituisce ready, processing o unavailable. L’allineamento completato viene memorizzato nella cache.
Autorizzazioni richieste:
POST https://api.voicecheap.ai/v1/actions/tts_align
Autenticazione e autorizzazioni
string
obbligatorio
Invia una chiave API VoiceCheap in questa intestazione. È supportato anche Authorization: Bearer con la stessa chiave API. I token di accesso OAuth
sono accettati solo da MCP, non da questo endpoint REST.
tts:write.
È necessario un abbonamento a pagamento attivo. Le autorizzazioni non modificano i ruoli del team, la proprietà delle risorse, i crediti multimediali o i limiti del piano.
Parametri
string
Facoltativo al livello di trasporto: se omesso, il server inserisce un identificatore prima della validazione. Fornisci un tuo UUID v4 stabile per recuperare in sicurezza una risposta persa.Formato: “uuid”. Pattern:
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$.string
obbligatorio
ID della cronologia restituito da tts_generate o tts_list.Pattern:
^(free-)?[0-9a-f]{64}$.Schema di input completo
Schema di input completo
Il JSON Schema seguente conserva i nomi esatti dei campi, i tipi annidati, i valori predefiniti, i limiti e i valori accettati esposti dalla discovery. Le ulteriori regole tra campi sono elencate nelle note sull’operazione.
{
"type": "object",
"properties": {
"requestId": {
"description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries.",
"type": "string",
"format": "uuid",
"pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"
},
"historyId": {
"type": "string",
"pattern": "^(free-)?[0-9a-f]{64}$",
"description": "History ID returned by tts_generate or tts_list."
}
},
"required": ["historyId"],
"additionalProperties": false
}
Idempotenza
Usa un UUID v4 in requestId o nell’intestazione HTTP Idempotency-Key per ogni modifica. Riutilizza lo stesso identificatore e argomenti identici dopo un errore di rete. Se vengono forniti entrambi, devono coincidere. Ripetere una richiesta salvata non ripete l’operazione e non consuma un’altra chiamata mensile. Le richieste non riuscite o interrotte non vengono riavviate automaticamente. Ogni modifica può restituire HTTP 202 quando un nuovo tentativo trova la stessa richiesta ancora in esecuzione, anche se la prima esecuzione è normalmente sincrona. Se l’esecuzione è completata ma resultStored è false, un nuovo tentativo restituisce HTTP 200 con lo stato della richiesta salvata anziché il risultato originale. Recupera l’output tramite l’azione di cronologia, risultato o download del relativo dominio.Esempi di richiesta
Sostituisci gli identificatori delle risorse e le chiavi multimediali di esempio con i valori restituiti per il tuo account. Mantieni stabile l’identificatore della richiesta quando ripeti la stessa modifica.curl --request POST 'https://api.voicecheap.ai/v1/actions/tts_align' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","historyId":"722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"}'
const input = {
requestId: '284a861a-4da8-4d67-ad48-8123e76c8e91',
historyId: '722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/tts_align', {
method: 'POST',
headers: {
'x-api-key': process.env.VOICECHEAP_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify(input),
});
const body = await response.json();
if (!response.ok) throw new Error(body.code + ': ' + body.message);
console.log(body);
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/tts_align",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91", "historyId": "722c80c6412edd4c3dcd625061e1c1feafbb0d54274d95fd8b5ca047f8cdd23d"},
timeout=120,
)
body = response.json()
if not response.ok:
raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
Risposta
Questa operazione restituisce HTTP 202 mentre è in esecuzione. Salva requestId e interroga action_request_get con questo identificatore e il nome dell’operazione originale. Gli stati del polling sono running, completed, failed e interrupted. Un risultato completato può rimandare a un processo multimediale separato; prosegui con l’azione di stato o di output specifica dell’operazione. Stato dell’allineamento e timestamp delle parole per l’audio vocale di proprietà dell’utente.{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"status": "running",
"pollAction": "action_request_get",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"status": "ready",
"wordAlignment": [
{
"text": "Hello",
"startSeconds": 0,
"endSeconds": 0.6,
"sourceStartCharacterIndex": 0,
"sourceEndCharacterIndex": 5
},
{
"text": "world.",
"startSeconds": 0.7,
"endSeconds": 1.4,
"sourceStartCharacterIndex": 6,
"sourceEndCharacterIndex": 12
}
]
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "tts_align",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "tts_align",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91"
}
Campi del risultato
| Campo | Descrizione |
|---|---|
data.status | ready, processing o unavailable. |
data.wordAlignment | Timestamp delle parole oppure null quando non è disponibile alcun allineamento. |
data.wordAlignment[].text | Testo della parola allineata. |
data.wordAlignment[].startSeconds | Tempo di inizio della parola in secondi. |
data.wordAlignment[].endSeconds | Tempo di fine della parola in secondi. |
data.wordAlignment[].sourceStartCharacterIndex | Indice del carattere iniziale in spokenText, dopo la rimozione dei tag di controllo dell’interpretazione vocale. |
data.wordAlignment[].sourceEndCharacterIndex | Indice del carattere finale in spokenText, dopo la rimozione dei tag di controllo dell’espressione vocale. |
Recupera e monitora questa richiesta
Usa lo stesso identificatore anche dopo una connessione persa. Se resultStored è false, recupera l’output tramite la corrispondente azione di cronologia, risultato o download. Non avviare mai una seconda generazione solo per verificarne l’avanzamento.curl --request POST 'https://api.voicecheap.ai/v1/actions/action_request_get' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"requestId":"284a861a-4da8-4d67-ad48-8123e76c8e91","operation":"tts_align"}'
HTTP 200
{
"data": {
"requestId": "284a861a-4da8-4d67-ad48-8123e76c8e91",
"operation": "tts_align",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"status": "ready",
"wordAlignment": [
{
"text": "Hello",
"startSeconds": 0,
"endSeconds": 0.6,
"sourceStartCharacterIndex": 0,
"sourceEndCharacterIndex": 5
},
{
"text": "world.",
"startSeconds": 0.7,
"endSeconds": 1.4,
"sourceStartCharacterIndex": 6,
"sourceEndCharacterIndex": 12
}
]
}
}
}
Note sull’operazione
- Usa un requestId UUID v4 per questa modifica e riutilizzalo con argomenti identici nei nuovi tentativi. Le azioni di lunga durata restituiscono inizialmente una richiesta in stato running; questo esempio è il risultato del gestore completato disponibile da action_request_get.
- status è ready con i timestamp, processing mentre è attivo un altro allineamento oppure unavailable quando al momento non è possibile produrre l’allineamento. processing e unavailable restituiscono wordAlignment: null.
- L’allineamento già completato correttamente viene memorizzato nella cache. Per un’anteprima dell’app viene allineata solo la parte udibile del testo; il completamento dell’anteprima richiede l’allineamento del nuovo audio completo.
- Gli indici dei caratteri sorgente fanno riferimento a spokenText dopo la rimozione dei tag supportati per il controllo dell’espressione vocale, come restituito da tts_get.
- Una richiesta di azione completata che ha restituito processing mantiene tale risultato registrato nelle ripetizioni idempotenti. Usa tts_get per esaminare i timestamp disponibili oppure avvia un nuovo controllo di allineamento con un nuovo requestId dopo il completamento dell’allineamento attivo.
- La cronologia dell’audio vocale e le voci personalizzate appartengono all’account autenticato. La fatturazione del team non concede accesso all’audio vocale o alle voci di un altro membro.
Utilizzo
Ogni invocazione riuscita consuma una chiamata API/MCP mensile. Si applicano anche i crediti multimediali e le quote di generazione proprie dell’operazione.Errori
| Stato HTTP | Codice | Significato o risoluzione |
|---|---|---|
| 400 | CREDENTIAL_IN_QUERY | Le credenziali sono state fornite in un parametro di query access_token o api_key. Invia le credenziali negli header. |
| 400 | IDEMPOTENCY_CONFLICT | L’intestazione Idempotency-Key e il campo requestId del corpo devono coincidere. |
| 400 | INVALID_REQUEST_ID | Fornisci requestId o Idempotency-Key come UUID v4. |
| 400 | VALIDATION_ERROR | L’input non corrisponde allo schema dell’azione; controlla details per gli errori dei campi. |
| 401 | API_KEY_EXPIRED | La chiave API è scaduta. |
| 401 | INVALID_API_KEY | Fornisci una chiave API valida e non scaduta. |
| 401 | INVALID_CREDENTIAL | L’header Authorization non è valido oppure è in conflitto con x-api-key. |
| 401 | MISSING_CREDENTIAL | Non è stata fornita alcuna credenziale utilizzabile negli header, oppure la credenziale superava 4096 caratteri. |
| 401 | USER_NOT_FOUND | L’account associato alla credenziale non esiste più. |
| 403 | ACCOUNT_UNAVAILABLE | L’account che esegue l’azione o quello di fatturazione non è disponibile o è in fase di eliminazione. |
| 403 | AMBIGUOUS_TEAM_API_KEY | L’utente della credenziale appartiene a più di un team, quindi il contesto di fatturazione è ambiguo. |
| 403 | INSUFFICIENT_SCOPE | Concedi tutte le autorizzazioni richieste o scegli un’altra credenziale. |
| 403 | INTEGRATION_PLAN_UNSUPPORTED | Impossibile verificare i limiti di integrazione dell’account. |
| 403 | SUBSCRIPTION_REQUIRED | Usa un abbonamento a pagamento attivo. |
| 403 | TEAM_OWNER_NOT_FOUND | Non è stato possibile trovare l’account effettivo del proprietario del team. |
| 404 | TEXT_TO_SPEECH_HISTORY_NOT_FOUND | L’elemento della cronologia della sintesi vocale non esiste oppure appartiene a un altro account. |
| 409 | CONCURRENT_ACTION_LIMIT_REACHED | Questo account ha già 10 azioni di integrazione in esecuzione. Interroga una richiesta esistente prima di avviarne un’altra. |
| 409 | IDEMPOTENCY_CONFLICT | Riutilizza un identificatore solo con la stessa operazione e gli stessi argomenti. |
| 429 | INTEGRATION_MONTHLY_LIMIT_REACHED | Attendi il ripristino mensile o cambia piano. |
| 429 | INTEGRATION_RATE_LIMIT_REACHED | Rispetta Retry-After quando presente e applica attese crescenti tra i tentativi. |
| 500 | INTERNAL_ERROR | Controlla lo stato della richiesta salvata e la cronologia delle risorse prima di decidere se ripetere una modifica. |
| 503 | ACTION_RESULT_UNAVAILABLE | L’azione è stata eseguita ma non è stato possibile salvarne il risultato. Esamina lo stato della richiesta salvata e la cronologia delle risorse prima di avviare una nuova generazione. |
| 503 | SERVER_RESTARTING | Il server si sta riavviando. Riprova tra poco e mantieni lo stesso identificatore della richiesta per una modifica. |
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["tts:write"]
}
}
Questa pagina è stata utile?