> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.voicecheap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Pubblica un video tradotto
> Pubblica o programma una traduzione completata, un output con sincronizzazione labiale o un output con sottotitoli dinamici su uno dei tuoi canali connessi. L'URL del video proviene dalla versione archiviata selezionata.
Pubblica o programma una traduzione completata, un output con sincronizzazione labiale o un output con sottotitoli dinamici su uno dei tuoi canali connessi. L'URL del video proviene dalla versione archiviata selezionata.
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/publishing_translation_create
```
## Autenticazione e autorizzazioni
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.
Autorizzazioni richieste: `publishing:write`, `projects:read`.
È 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
Valore testuale.
Lunghezza minima: 1. Lunghezza massima: 200. Pattern: `^[^/\\]+$`.
Valore testuale.
Lunghezza minima: 1. Lunghezza massima: 200. Pattern: `^[^/\\]+$`.
Valore testuale.
Lunghezza minima: 1. Lunghezza massima: 200. Pattern: `^[^/\\]+$`.
Valore testuale.
Valori consentiti: "youtube", "tiktok".
Valore testuale.
Lunghezza minima: 1. Lunghezza massima: 200. Pattern: `^[^/\\]+$`.
Valore testuale.
Valori consentiti: "translated", "lip-synced", "dynamic-subtitles". Valore predefinito: "translated".
Valore testuale.
Lunghezza minima: 1. Lunghezza massima: 100.
Valore testuale.
Lunghezza massima: 5000.
Valore testuale.
Valori consentiti: "public", "unlisted", "private". Valore predefinito: "private".
Valore testuale.
Valori consentiti: "PUBLIC\_TO\_EVERYONE", "MUTUAL\_FOLLOW\_FRIENDS", "FOLLOWER\_OF\_CREATOR", "SELF\_ONLY". Valore predefinito: "SELF\_ONLY".
Valore testuale.
Formato: "date-time". Pattern: `^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$`.
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}$`.
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.
```json theme={null}
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/\\\\]+$"
},
"workId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/\\\\]+$"
},
"translatedVersionId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/\\\\]+$"
},
"platform": {
"type": "string",
"enum": ["youtube", "tiktok"]
},
"channelId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[^/\\\\]+$"
},
"videoSource": {
"default": "translated",
"type": "string",
"enum": ["translated", "lip-synced", "dynamic-subtitles"]
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"description": {
"type": "string",
"maxLength": 5000
},
"youtubePrivacyStatus": {
"default": "private",
"type": "string",
"enum": ["public", "unlisted", "private"]
},
"tiktokPrivacyLevel": {
"default": "SELF_ONLY",
"type": "string",
"enum": ["PUBLIC_TO_EVERYONE", "MUTUAL_FOLLOW_FRIENDS", "FOLLOWER_OF_CREATOR", "SELF_ONLY"]
},
"scheduledAt": {
"type": "string",
"format": "date-time",
"pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
},
"requestId": {
"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}$",
"description": "UUID v4 for this action. Reuse the same ID with identical arguments on retries."
}
},
"required": ["projectId", "workId", "translatedVersionId", "platform", "channelId", "title"],
"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.
```bash cURL theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/publishing_translation_create' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"projectId":"project_launch_2026","workId":"5f8423d1-e4c0-4f80-9e3f-eed959389e24","translatedVersionId":"0fa684f3-4997-4d7a-9424-16d1f9ac849c","platform":"youtube","channelId":"UC1234567890abcdefghijkl","videoSource":"translated","title":"English product launch","description":"Our latest product update.","youtubePrivacyStatus":"private","scheduledAt":"2030-10-16T12:00:00+02:00","requestId":"41321bda-e243-4b6f-96a4-622cd047c991"}'
```
```javascript JavaScript theme={null}
const input = {
projectId: 'project_launch_2026',
workId: '5f8423d1-e4c0-4f80-9e3f-eed959389e24',
translatedVersionId: '0fa684f3-4997-4d7a-9424-16d1f9ac849c',
platform: 'youtube',
channelId: 'UC1234567890abcdefghijkl',
videoSource: 'translated',
title: 'English product launch',
description: 'Our latest product update.',
youtubePrivacyStatus: 'private',
scheduledAt: '2030-10-16T12:00:00+02:00',
requestId: '41321bda-e243-4b6f-96a4-622cd047c991',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/publishing_translation_create', {
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);
```
```python Python theme={null}
import os
import requests
response = requests.post(
"https://api.voicecheap.ai/v1/actions/publishing_translation_create",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"projectId": "project_launch_2026", "workId": "5f8423d1-e4c0-4f80-9e3f-eed959389e24", "translatedVersionId": "0fa684f3-4997-4d7a-9424-16d1f9ac849c", "platform": "youtube", "channelId": "UC1234567890abcdefghijkl", "videoSource": "translated", "title": "English product launch", "description": "Our latest product update.", "youtubePrivacyStatus": "private", "scheduledAt": "2030-10-16T12:00:00+02:00", "requestId": "41321bda-e243-4b6f-96a4-622cd047c991"},
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.
Restituisce un'identità e un timestamp della pubblicazione pianificata oppure un'identità e un URL del video pubblicato immediatamente.
```json HTTP 202 theme={null}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"status": "running",
"pollAction": "action_request_get",
"pollAfterSeconds": 5
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
```
```json HTTP 200 theme={null}
{
"data": {
"publicationId": "7db6b953-7664-4bc2-811a-6aa7aa29038d",
"projectId": "project_launch_2026",
"platform": "youtube",
"status": "scheduled",
"scheduledAt": 1918375200000
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
```
```json HTTP 202 replay_running theme={null}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "publishing_translation_create",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "running",
"pollAfterSeconds": 5
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
```
```json HTTP 200 replay_completed_without_result theme={null}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "publishing_translation_create",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"status": "completed",
"resultStored": false,
"message": "The action completed. Retrieve its output from the corresponding history or resource action."
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
```
## Campi del risultato
| Campo | Descrizione |
| - | - |
| `data.publicationId` | Identificatore del nuovo tentativo di pubblicazione o della pubblicazione pianificata. |
| `data.projectId` | Identificatore del progetto padre. |
| `data.platform` | youtube o tiktok. |
| `data.status` | scheduled quando viene creata una pianificazione; published nel ramo con risposta immediata. |
| `data.scheduledAt` | Ora di programmazione in millisecondi Unix; presente soltanto nel ramo di pubblicazione programmata. |
| `data.videoId` | Identificatore del video sulla piattaforma social; solo nel ramo immediato. |
| `data.videoUrl` | URL del video sulla piattaforma, quando restituito dal servizio di pubblicazione; solo nel ramo di pubblicazione immediata. |
## scheduledAt viene omesso e il servizio di pubblicazione immediata si conclude.
Restituisce l'identità del tentativo di pubblicazione immediata e le informazioni sul video della piattaforma.
```json HTTP 200 theme={null}
{
"data": {
"publicationId": "7db6b953-7664-4bc2-811a-6aa7aa29038d",
"projectId": "project_launch_2026",
"platform": "youtube",
"status": "published",
"videoId": "example1234",
"videoUrl": "https://www.youtube.com/watch?v=example1234"
}
}
```
## 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.
```bash theme={null}
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":"41321bda-e243-4b6f-96a4-622cd047c991","operation":"publishing_translation_create"}'
```
```json HTTP 200 theme={null}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "publishing_translation_create",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"publicationId": "7db6b953-7664-4bc2-811a-6aa7aa29038d",
"projectId": "project_launch_2026",
"platform": "youtube",
"status": "scheduled",
"scheduledAt": 1918375200000
}
}
}
```
## Note sull'operazione
* Questa azione pubblica esternamente. Seleziona un canale appartenente all'utente autenticato; l'accesso ai contenuti multimediali dei progetti del team non concede accesso al canale di un altro membro.
* Il valore predefinito di videoSource è translated. lip-synced seleziona l'ultimo video completato con sincronizzazione labiale; dynamic-subtitles seleziona l'output memorizzato dei sottotitoli dinamici. La versione deve essere nello stato completed e l'output scelto deve esistere.
* L'integrazione usa per impostazione predefinita YouTube private e TikTok SELF\_ONLY. L'URL del video proviene dalla versione memorizzata autorizzata, non da un URL fornito dal chiamante.
* scheduledAt è opzionale. Se fornito, deve essere una data e ora ISO valida con un offset e strettamente futura; il gestore ne restituisce il valore in millisecondi Unix. In sua assenza, questa azione pubblica immediatamente.
* Questa azione richiede un'esecuzione prolungata. Interroga periodicamente action\_request\_get per ottenere il risultato del gestore e publishing\_list per lo stato successivo della pubblicazione. Le risposte programmate e immediate hanno campi diversi.
* Il gestore immediato riporta lo stato published con il videoId restituito dal servizio di pubblicazione sui social e il videoUrl facoltativo. La risposta della pianificazione in coda non contiene videoId né videoUrl.
* Per TikTok, videoId può essere l'identificatore di pubblicazione della piattaforma quando l'ID numerico finale del video non è disponibile; videoUrl può usare come alternativa l'URL del canale connesso o il video di origine archiviato.
## 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 | `INVALID_SCHEDULE` | scheduledAt non indica un istante futuro. |
| 400 | `OUTPUT_NOT_READY` | L'output video selezionato tradotto, con lip-sync o con sottotitoli è mancante. |
| 400 | `TRANSLATION_NOT_READY` | La versione tradotta selezionata non è in stato completed. |
| 400 | `VALIDATION_ERROR` | Correggi l'input usando lo schema. I valori non validi o incoerenti vengono rifiutati prima dell'esecuzione. |
| 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 | `FORBIDDEN` | L'utente chiamante autenticato non può accedere a questo progetto. |
| 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 | `PUBLISHING_CHANNEL_FORBIDDEN` | Il canale non appartiene all'utente chiamante autenticato. |
| 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 | `PROJECT_NOT_FOUND` | Il progetto non esiste nell'account accessibile. |
| 404 | `TRANSLATION_NOT_FOUND` | workId non identifica un lavoro linguistico appartenente a questo progetto. |
| 404 | `TRANSLATION_VERSION_NOT_FOUND` | translatedVersionId non appartiene al lavoro linguistico selezionato. |
| 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` | Non è stato possibile completare la pubblicazione. Esamina la richiesta e la cronologia delle pubblicazioni prima di riprovare. |
| 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. |
```json theme={null}
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["publishing:write", "projects:read"]
}
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.