> ## 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. # Publicar um vídeo traduzido > Publique ou agende uma tradução concluída, uma saída com sincronização labial ou uma saída com legendas dinâmicas em um dos seus próprios canais conectados. A URL do vídeo vem da versão armazenada selecionada. Publique ou agende uma tradução concluída, uma saída com sincronização labial ou uma saída com legendas dinâmicas em um dos seus próprios canais conectados. A URL do vídeo vem da versão armazenada selecionada. ```http theme={null} POST https://api.voicecheap.ai/v1/actions/publishing_translation_create ``` ## Autenticação e permissões Envie uma chave de API VoiceCheap neste cabeçalho. Authorization: Bearer com a mesma chave de API também é aceito. Tokens de acesso OAuth são aceitos apenas pelo MCP, não por este endpoint REST. Permissões necessárias: `publishing:write`, `projects:read`. É necessária uma assinatura paga ativa. As permissões não alteram funções na equipe, propriedade dos recursos, créditos de mídia ou limites do plano. ## Parâmetros Valor de texto. Comprimento mínimo: 1. Comprimento máximo: 200. Padrão: `^[^/\\]+$`. Valor de texto. Comprimento mínimo: 1. Comprimento máximo: 200. Padrão: `^[^/\\]+$`. Valor de texto. Comprimento mínimo: 1. Comprimento máximo: 200. Padrão: `^[^/\\]+$`. Valor de texto. Valores aceitos: "youtube", "tiktok". Valor de texto. Comprimento mínimo: 1. Comprimento máximo: 200. Padrão: `^[^/\\]+$`. Valor de texto. Valores aceitos: "translated", "lip-synced", "dynamic-subtitles". Valor padrão: "translated". Valor de texto. Comprimento mínimo: 1. Comprimento máximo: 100. Valor de texto. Comprimento máximo: 5000. Valor de texto. Valores aceitos: "public", "unlisted", "private". Valor padrão: "private". Valor de texto. Valores aceitos: "PUBLIC\_TO\_EVERYONE", "MUTUAL\_FOLLOW\_FRIENDS", "FOLLOWER\_OF\_CREATOR", "SELF\_ONLY". Valor padrão: "SELF\_ONLY". Valor de texto. Formato: "date-time". Padrão: `^(?:(?:\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)))$`. Opcional na camada de transporte: o servidor insere um identificador antes da validação quando ele é omitido. Forneça seu próprio UUID v4 estável para recuperar com segurança uma resposta perdida. Formato: "uuid". Padrão: `^[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}$`. O JSON Schema abaixo preserva os nomes exatos dos campos, tipos aninhados, valores padrão, limites e valores aceitos expostos pela descoberta. Regras adicionais entre campos são listadas nas notas da operação. ```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 } ``` ## Idempotência Use um UUID v4 em requestId ou no cabeçalho HTTP Idempotency-Key para cada alteração. Reutilize o mesmo identificador e argumentos idênticos após uma falha de rede. Se ambos forem fornecidos, devem ser iguais. Repetir uma requisição salva não repete a operação nem consome outra chamada mensal. Requisições com falha ou interrompidas não são reiniciadas automaticamente. Qualquer alteração pode retornar HTTP 202 quando uma nova tentativa encontra a mesma requisição ainda em execução, mesmo que a primeira execução normalmente seja síncrona. Se a execução foi concluída, mas resultStored é false, uma nova tentativa retorna HTTP 200 com o estado salvo da requisição em vez do resultado original. Recupere a saída pela ação de histórico, resultado ou download do domínio correspondente. ## Exemplos de requisição Substitua os identificadores de recursos e as chaves de mídia dos exemplos pelos valores retornados para sua conta. Mantenha o identificador da requisição ao tentar novamente a mesma alteração. ```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) ``` ## Resposta Esta operação retorna HTTP 202 enquanto está em execução. Salve requestId e consulte action\_request\_get com esse identificador e o nome da operação original. Os estados de consulta são running, completed, failed e interrupted. Um resultado concluído pode apontar para um processamento de mídia separado; continue com a ação de status ou de saída específica da operação. Retorna uma identidade de publicação agendada e seu timestamp ou uma identidade e URL de vídeo publicado imediatamente. ```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" } ``` ## Campos do resultado | Campo | Descrição | | - | - | | `data.publicationId` | Identificador da nova tentativa de publicação ou da publicação planejada. | | `data.projectId` | Identificador do projeto pai. | | `data.platform` | youtube ou tiktok. | | `data.status` | scheduled quando um agendamento é criado; published no fluxo de resposta imediata. | | `data.scheduledAt` | Horário de agendamento em milissegundos Unix; presente apenas no fluxo de publicação agendada. | | `data.videoId` | Identificador do vídeo na plataforma social; somente no ramo de publicação imediata. | | `data.videoUrl` | URL do vídeo na plataforma quando retornada pelo publicador; apenas no fluxo de publicação imediata. | ## scheduledAt é omitido e o serviço de publicação imediata conclui sua execução. Retorna a identidade da tentativa imediata de publicação e as informações do vídeo na plataforma. ```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" } } ``` ## Recuperar e consultar esta requisição Use o mesmo identificador mesmo após perder a conexão. Se resultStored for false, recupere a saída pela ação correspondente de histórico, resultado ou download. Nunca inicie uma segunda geração apenas para verificar o progresso. ```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 } } } ``` ## Notas da operação * Isso publica externamente. Selecione um canal pertencente ao ator autenticado; a mídia acessível de projetos da equipe não concede acesso ao canal de outro membro. * O padrão de videoSource é translated. lip-synced seleciona o vídeo concluído mais recente com sincronização labial; dynamic-subtitles seleciona a saída armazenada de legendas dinâmicas. A versão deve estar concluída e a saída escolhida deve existir. * A integração usa por padrão private no YouTube e SELF\_ONLY no TikTok. A URL do vídeo vem da versão armazenada autorizada, e não de uma URL fornecida pelo chamador. * scheduledAt é opcional. Quando fornecido, deve ser uma data e hora ISO válida com um deslocamento de fuso e estritamente no futuro; o handler retorna seu valor em milissegundos Unix. Sem ele, esta ação publica imediatamente. * Esta é uma ação de longa duração. Consulte action\_request\_get periodicamente para obter o resultado do processador e publishing\_list para o estado posterior da publicação. As respostas agendadas e imediatas têm campos diferentes. * O manipulador imediato informa o status published com o videoId e o videoUrl opcional retornados pelo serviço de publicação em redes sociais. A resposta de agendamento na fila não contém videoId nem videoUrl. * Para o TikTok, videoId pode ser o identificador de publicação da plataforma quando um ID numérico final do vídeo não está disponível; videoUrl pode usar como alternativa a URL do canal conectado ou o vídeo de origem armazenado. ## Uso Cada chamada bem-sucedida consome uma chamada mensal da API/MCP. Os créditos de mídia e as cotas de geração da própria operação também se aplicam. ## Erros | Status HTTP | Código | Significado ou recuperação | | - | - | - | | 400 | `CREDENTIAL_IN_QUERY` | Foram fornecidas credenciais em um parâmetro de consulta access\_token ou api\_key. Envie as credenciais nos cabeçalhos. | | 400 | `IDEMPOTENCY_CONFLICT` | O cabeçalho Idempotency-Key e o campo requestId do corpo devem ser iguais. | | 400 | `INVALID_REQUEST_ID` | Forneça um requestId ou Idempotency-Key no formato UUID v4. | | 400 | `INVALID_SCHEDULE` | scheduledAt não está no futuro. | | 400 | `OUTPUT_NOT_READY` | A saída de vídeo traduzido, com sincronização labial ou com legendas selecionada está ausente. | | 400 | `TRANSLATION_NOT_READY` | A versão traduzida selecionada não está concluída. | | 400 | `VALIDATION_ERROR` | Corrija a entrada usando o esquema. Valores inválidos ou inconsistentes são rejeitados antes da execução. | | 401 | `API_KEY_EXPIRED` | A chave de API expirou. | | 401 | `INVALID_API_KEY` | Forneça uma chave de API válida e dentro do prazo de validade. | | 401 | `INVALID_CREDENTIAL` | O cabeçalho Authorization está malformado ou entra em conflito com x-api-key. | | 401 | `MISSING_CREDENTIAL` | Nenhuma credencial utilizável foi fornecida no cabeçalho, ou ela excedeu 4096 caracteres. | | 401 | `USER_NOT_FOUND` | A conta da credencial não existe mais. | | 403 | `ACCOUNT_UNAVAILABLE` | A conta que executa a ação ou a conta de cobrança está indisponível ou em processo de exclusão. | | 403 | `AMBIGUOUS_TEAM_API_KEY` | O usuário da credencial pertence a mais de uma equipe, portanto o contexto de cobrança é ambíguo. | | 403 | `FORBIDDEN` | O autor autenticado da ação não pode acessar este projeto. | | 403 | `INSUFFICIENT_SCOPE` | Conceda todas as permissões necessárias ou escolha outra credencial. | | 403 | `INTEGRATION_PLAN_UNSUPPORTED` | Não foi possível verificar os limites de integração da conta. | | 403 | `PUBLISHING_CHANNEL_FORBIDDEN` | O canal não pertence ao autor autenticado da ação. | | 403 | `SUBSCRIPTION_REQUIRED` | Use uma assinatura paga ativa. | | 403 | `TEAM_OWNER_NOT_FOUND` | Não foi possível encontrar a conta efetiva do proprietário da equipe. | | 404 | `PROJECT_NOT_FOUND` | O projeto não existe na conta acessível. | | 404 | `TRANSLATION_NOT_FOUND` | workId não identifica um trabalho de idioma pertencente a este projeto. | | 404 | `TRANSLATION_VERSION_NOT_FOUND` | translatedVersionId não pertence ao trabalho de idioma selecionado. | | 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | Esta conta já tem 10 ações de integração em execução. Consulte uma requisição existente antes de iniciar outra. | | 409 | `IDEMPOTENCY_CONFLICT` | Reutilize um identificador apenas com a mesma operação e os mesmos argumentos. | | 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Aguarde a renovação do limite mensal ou mude de plano. | | 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Aguarde o prazo de Retry-After, quando presente, e aumente progressivamente o intervalo entre as tentativas. | | 500 | `INTERNAL_ERROR` | Não foi possível concluir a publicação. Inspecione a requisição e o histórico de publicação antes de tentar novamente. | | 503 | `ACTION_RESULT_UNAVAILABLE` | A ação foi executada, mas não foi possível salvar seu resultado. Inspecione o estado salvo da requisição e o histórico do recurso antes de iniciar uma nova geração. | | 503 | `SERVER_RESTARTING` | O servidor está reiniciando. Tente novamente em breve e mantenha o mesmo identificador de requisição para uma alteração. | ```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.