> ## 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.
# Publish a translated video
> Publish or schedule a completed translation, lip-synced output or dynamic subtitle output to one of your own connected channels. The video URL comes from the selected stored version.
Publish or schedule a completed translation, lip-synced output or dynamic subtitle output to one of your own connected channels. The video URL comes from the selected stored version.
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/publishing_translation_create
```
## Authentication and permissions
Send a VoiceCheap API key in this header. Authorization: Bearer with the same API key is also supported. OAuth access tokens are accepted only by
MCP, not by this REST endpoint.
Required permissions: `publishing:write`, `projects:read`.
An active paid subscription is required. Permissions do not change team roles, resource ownership, media credits, or plan limits.
## Parameters
Text value.
Minimum length: 1. Maximum length: 200. Pattern: `^[^/\\]+$`.
Text value.
Minimum length: 1. Maximum length: 200. Pattern: `^[^/\\]+$`.
Text value.
Minimum length: 1. Maximum length: 200. Pattern: `^[^/\\]+$`.
Text value.
Allowed values: "youtube", "tiktok".
Text value.
Minimum length: 1. Maximum length: 200. Pattern: `^[^/\\]+$`.
Text value.
Allowed values: "translated", "lip-synced", "dynamic-subtitles". Default: "translated".
Text value.
Minimum length: 1. Maximum length: 100.
Text value.
Maximum length: 5000.
Text value.
Allowed values: "public", "unlisted", "private". Default: "private".
Text value.
Allowed values: "PUBLIC\_TO\_EVERYONE", "MUTUAL\_FOLLOW\_FRIENDS", "FOLLOWER\_OF\_CREATOR", "SELF\_ONLY". Default: "SELF\_ONLY".
Text value.
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)))$`.
Optional at the transport boundary: the server injects an identifier before validation when omitted. Supply your own stable UUID v4 to recover safely from a lost response.
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}$`.
The JSON Schema below preserves the exact field names, nested types, defaults, bounds, and accepted values exposed by discovery. Additional cross-field rules are listed in the operation notes.
```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
}
```
## Idempotency
Use a UUID v4 in requestId or the Idempotency-Key HTTP header for each mutation. Reuse the same identifier and identical arguments after a network failure. If both are supplied, they must match. Replaying a saved request does not repeat the operation or charge another monthly call. Failed or interrupted requests are not restarted automatically.
Every mutation can return HTTP 202 when a retry finds the same request still running, even when its first execution is normally synchronous. If execution completed but resultStored is false, a retry returns HTTP 200 with saved request state instead of the original result. Retrieve the output through its domain history, result, or download action.
## Request examples
Replace example resource identifiers and media keys with values returned for your account. Keep the request identifier stable when retrying the same mutation.
```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)
```
## Response
This operation returns HTTP 202 while running. Save requestId and poll action\_request\_get with that identifier and the original operation name. Polling states are running, completed, failed, and interrupted. A completed result can point to a separate media job; continue with the operation-specific status or output action.
Returns either a scheduled publication identity and timestamp or an immediate published-video identity and URL.
```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"
}
```
## Result fields
| Field | Description |
| - | - |
| `data.publicationId` | New publication attempt or planned-publication identifier. |
| `data.projectId` | Parent project identifier. |
| `data.platform` | youtube or tiktok. |
| `data.status` | scheduled when a schedule is created; published on the immediate response branch. |
| `data.scheduledAt` | Unix-millisecond schedule time; present only on the scheduled branch. |
| `data.videoId` | Social platform video identifier; immediate branch only. |
| `data.videoUrl` | Platform video URL when returned by the publisher; immediate branch only. |
## scheduledAt is omitted and the immediate publishing service resolves.
Returns the immediate publication attempt identity and platform video information.
```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"
}
}
```
## Recover and poll this request
Use the same identifier even after a lost connection. If resultStored is false, retrieve the output through the corresponding history, result, or download action. Never start a second generation merely to check progress.
```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
}
}
}
```
## Operation notes
* This publishes externally. Select one channel belonging to the authenticated actor; accessible team project media does not grant access to another member's channel.
* videoSource defaults to translated. lip-synced selects the latest completed lip-sync video; dynamic-subtitles selects the stored dynamic-subtitle output. The version must be completed and the chosen output must exist.
* The integration defaults to YouTube private and TikTok SELF\_ONLY. The video URL comes from the authorized stored version, not a caller-supplied URL.
* scheduledAt is optional. When supplied it must be a valid ISO datetime with an offset and strictly in the future; the handler returns its Unix-millisecond value. Without it, this action publishes immediately.
* This is a long-running action. Poll action\_request\_get for the handler result and publishing\_list for subsequent publication state. Scheduled and immediate responses have different fields.
* The immediate handler reports status published with the social publishing service's returned videoId and optional videoUrl. The queued schedule response has no videoId or videoUrl.
* For TikTok, videoId may be the platform publication identifier when a final numeric video id is unavailable; videoUrl may fall back to the connected channel URL or stored source video.
## Usage
Each successful invocation consumes one monthly API/MCP call. Media credits and the operation's own generation allowances also apply.
## Errors
| HTTP status | Code | Meaning or recovery |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | Credentials were supplied in an access\_token or api\_key query parameter. Send credentials in headers. |
| 400 | `IDEMPOTENCY_CONFLICT` | The Idempotency-Key header and requestId body field must match. |
| 400 | `INVALID_REQUEST_ID` | Supply a UUID v4 requestId or Idempotency-Key. |
| 400 | `INVALID_SCHEDULE` | scheduledAt is not in the future. |
| 400 | `OUTPUT_NOT_READY` | The selected translated, lip-synced or subtitle video output is missing. |
| 400 | `TRANSLATION_NOT_READY` | The selected translated version is not completed. |
| 400 | `VALIDATION_ERROR` | Correct the input using the schema. Invalid or inconsistent values are rejected before execution. |
| 401 | `API_KEY_EXPIRED` | The API key has expired. |
| 401 | `INVALID_API_KEY` | Provide a valid, unexpired API key. |
| 401 | `INVALID_CREDENTIAL` | The Authorization header is malformed or conflicts with x-api-key. |
| 401 | `MISSING_CREDENTIAL` | No usable header credential was supplied, or it exceeded 4096 characters. |
| 401 | `USER_NOT_FOUND` | The credential's account no longer exists. |
| 403 | `ACCOUNT_UNAVAILABLE` | The acting or billing account is unavailable or being deleted. |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | The credential's user belongs to more than one team, so the billing context is ambiguous. |
| 403 | `FORBIDDEN` | The authenticated actor cannot access this project. |
| 403 | `INSUFFICIENT_SCOPE` | Grant every required permission or choose another credential. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | The account's integration limits could not be verified. |
| 403 | `PUBLISHING_CHANNEL_FORBIDDEN` | The channel does not belong to the authenticated actor. |
| 403 | `SUBSCRIPTION_REQUIRED` | Use an active paid subscription. |
| 403 | `TEAM_OWNER_NOT_FOUND` | The effective team owner account could not be found. |
| 404 | `PROJECT_NOT_FOUND` | The project does not exist in the accessible account. |
| 404 | `TRANSLATION_NOT_FOUND` | workId does not identify a language work owned by this project. |
| 404 | `TRANSLATION_VERSION_NOT_FOUND` | translatedVersionId does not belong to the selected language work. |
| 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | This account already has 10 integration actions running. Poll an existing request before starting another. |
| 409 | `IDEMPOTENCY_CONFLICT` | Reuse an identifier only with the same operation and arguments. |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | Wait for the monthly reset or change plan. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Wait for Retry-After when present and use backoff. |
| 500 | `INTERNAL_ERROR` | Publication could not be completed. Inspect request and publication history before retrying. |
| 503 | `ACTION_RESULT_UNAVAILABLE` | The action ran but its result could not be saved. Inspect saved request state and resource history before starting a new generation. |
| 503 | `SERVER_RESTARTING` | The server is restarting. Retry shortly and keep the same request identifier for a mutation. |
```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.