> ## 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.

# Duplicate saved subtitles

> Save a separate editable copy of subtitles without generating another transcript.

Save a separate editable copy of subtitles without generating another transcript.

```http theme={null}
POST https://api.voicecheap.ai/v1/actions/subtitles_history_duplicate
```

## Authentication and permissions

**x-api-key** `string` *required*

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: `subtitles:write`.

An active paid subscription is required. Permissions do not change team roles, resource ownership, media credits, or plan limits.

## Parameters

**historyId** `string` *required*

Text value.

Minimum length: 1. Maximum length: 160. Pattern: `^[A-Za-z0-9_-]+$`.

**currentSrtContent** `string` *required*

Text value.

Minimum length: 1. Maximum length: 2097152.

**layoutOptions** `object`

JSON object. See the complete input schema for its nested fields.

**styleOptions** `object`

JSON object. See the complete input schema for its nested fields.

**requestId** `string`

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}$`.

> [accordion] Complete input schema
>
> 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": {
>     "historyId": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 160,
>       "pattern": "^[A-Za-z0-9_-]+$"
>     },
>     "currentSrtContent": {
>       "type": "string",
>       "minLength": 1,
>       "maxLength": 2097152
>     },
>     "layoutOptions": {
>       "type": "object",
>       "properties": {
>         "maxLinesPerCaption": {
>           "anyOf": [
>             {
>               "type": "number",
>               "const": 1
>             },
>             {
>               "type": "number",
>               "const": 2
>             },
>             {
>               "type": "number",
>               "const": 3
>             }
>           ]
>         },
>         "maxCharactersPerLine": {
>           "type": "integer",
>           "minimum": 24,
>           "maximum": 64
>         }
>       },
>       "required": ["maxLinesPerCaption", "maxCharactersPerLine"],
>       "additionalProperties": false
>     },
>     "styleOptions": {
>       "type": "object",
>       "properties": {
>         "fontFamily": {
>           "type": "string",
>           "enum": ["sans", "serif", "mono"]
>         },
>         "fontSize": {
>           "type": "string",
>           "enum": ["small", "medium", "large"]
>         },
>         "textColor": {
>           "type": "string",
>           "enum": ["white", "yellow", "cyan"]
>         },
>         "backgroundStyle": {
>           "type": "string",
>           "enum": ["outline", "box", "shadow"]
>         },
>         "position": {
>           "type": "string",
>           "enum": ["bottom", "middle"]
>         }
>       },
>       "required": ["fontFamily", "fontSize", "textColor", "backgroundStyle", "position"],
>       "additionalProperties": false
>     },
>     "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}$"
>     }
>   },
>   "required": ["historyId", "currentSrtContent"],
>   "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/subtitles_history_duplicate' \
  --header "x-api-key: $VOICECHEAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"historyId":"history_20261016_001","currentSrtContent":"1\n00:00:00,000 --> 00:00:01,500\nHello world.\n","layoutOptions":{"maxLinesPerCaption":2,"maxCharactersPerLine":42},"styleOptions":{"fontFamily":"sans","fontSize":"medium","textColor":"white","backgroundStyle":"outline","position":"bottom"},"requestId":"13579bdf-2468-4ace-8bdf-0123456789ab"}'
```

```javascript JavaScript theme={null}
const input = {
  historyId: 'history_20261016_001',
  currentSrtContent: '1\n00:00:00,000 --> 00:00:01,500\nHello world.\n',
  layoutOptions: {
    maxLinesPerCaption: 2,
    maxCharactersPerLine: 42,
  },
  styleOptions: {
    fontFamily: 'sans',
    fontSize: 'medium',
    textColor: 'white',
    backgroundStyle: 'outline',
    position: 'bottom',
  },
  requestId: '13579bdf-2468-4ace-8bdf-0123456789ab',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/subtitles_history_duplicate', {
  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/subtitles_history_duplicate",
    headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
    json={"historyId": "history_20261016_001", "currentSrtContent": "1\n00:00:00,000 --> 00:00:01,500\nHello world.\n", "layoutOptions": {"maxLinesPerCaption": 2, "maxCharactersPerLine": 42}, "styleOptions": {"fontFamily": "sans", "fontSize": "medium", "textColor": "white", "backgroundStyle": "outline", "position": "bottom"}, "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"},
    timeout=120,
)
body = response.json()
if not response.ok:
    raise RuntimeError(f"{body.get('code')}: {body.get('message')}")
print(body)
```

## Response

A successful first execution returns HTTP 200 with the operation result under data. A replay may return saved request state instead. The example shows one supported response, not every optional field.

A new independently editable subtitle history ID starting at revision 1, with its normalized SRT and creation timestamp.

```json HTTP 200 theme={null}
{
  "data": {
    "historyId": "history_20261016_copy",
    "revision": 1,
    "updatedAt": 1792152010000,
    "currentSrtContent": "1\n00:00:00,000 --> 00:00:01,500\nHello world.\n"
  },
  "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}
```

```json HTTP 202 replay_running theme={null}
{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "operation": "subtitles_history_duplicate",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "running",
    "pollAfterSeconds": 5
  },
  "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}
```

```json HTTP 200 replay_completed_without_result theme={null}
{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "operation": "subtitles_history_duplicate",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "status": "completed",
    "resultStored": false,
    "message": "The action completed. Retrieve its output from the corresponding history or resource action."
  },
  "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab"
}
```

## Result fields

| Field | Description |
| - | - |
| `data.historyId` | New saved subtitle item, distinct from the input historyId. |
| `data.revision` | 1 for the new editable copy. |
| `data.updatedAt` | Unix timestamp in milliseconds for the newly created copy. |
| `data.currentSrtContent` | Normalized supplied subtitle content. |

## 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":"13579bdf-2468-4ace-8bdf-0123456789ab","operation":"subtitles_history_duplicate"}'
```

```json HTTP 200 theme={null}
{
  "data": {
    "requestId": "13579bdf-2468-4ace-8bdf-0123456789ab",
    "operation": "subtitles_history_duplicate",
    "status": "completed",
    "createdAt": 1792144800000,
    "updatedAt": 1792144820000,
    "resultStored": true,
    "result": {
      "historyId": "history_20261016_copy",
      "revision": 1,
      "updatedAt": 1792152010000,
      "currentSrtContent": "1\n00:00:00,000 --> 00:00:01,500\nHello world.\n"
    }
  }
}
```

## Operation notes

* Requires a paid subscription and the action permission. The actor's personal tool plan is rechecked at execution; saved tools and upload references belong to that actor, including when the credential is associated with a team.
* A successful action uses one shared monthly API/MCP call. Beginner allows 500, Starter 5,000 and Creator 25,000 calls/month; Pro, Scale and Enterprise have no monthly ceiling. Per-minute limits still apply: 30, 60, 120, 180, 300 and 600 respectively. Tool generation allowances are separate.
* Use a UUID v4 requestId, or an identical Idempotency-Key header, and retain the same action, ID and arguments on retries. A cached replay does not use another monthly call.
* The input historyId selects the actor-owned source. Supply the full currentSrtContent to copy; it is not automatically taken from the saved source.
* Cue validation and the 2 MiB bound match subtitles\_history\_update. Omitted layoutOptions/styleOptions use standard defaults.
* A duplicate does not generate a new transcript, consume an uploaded source or use a daily tool generation. It does use one successful monthly integration call.

## 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 header and body request IDs differ. |
| 400 | `INVALID_REQUEST_ID` | requestId or Idempotency-Key is not a UUID v4. |
| 400 | `VALIDATION_ERROR` | Arguments do not satisfy the action schema, or an unknown argument was supplied. |
| 400 | `VIDEO_TO_SRT_HISTORY_INVALID_SRT` | SRT cue text or timestamp structure is invalid. |
| 400 | `VIDEO_TO_SRT_HISTORY_OUTSIDE_MEDIA` | A cue ends beyond the recorded source duration plus its 0.5-second tolerance. |
| 400 | `VIDEO_TO_SRT_HISTORY_OVERLAP` | At least two subtitle cues overlap. |
| 400 | `VIDEO_TO_SRT_HISTORY_SRT_TOO_LARGE` | Edited SRT exceeds the 2 MiB UTF-8 limit. |
| 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 | `INSUFFICIENT_SCOPE` | The API key or MCP connection lacks the required action permission. |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | The account's integration limits could not be verified. |
| 403 | `PAID_SUBSCRIPTION_REQUIRED` | The authenticated actor no longer has a paid subscription when this tool action executes. |
| 403 | `SUBSCRIPTION_REQUIRED` | Use an active paid subscription. |
| 403 | `TEAM_OWNER_NOT_FOUND` | The effective team owner account could not be found. |
| 404 | `VIDEO_TO_SRT_HISTORY_NOT_FOUND` | The actor-owned editable subtitle history item does not exist. |
| 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` | Used and pending calls have reached the shared monthly API/MCP allowance. |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | The account has reached its per-minute integration limit; inspect retryAfterSeconds. |
| 500 | `INTERNAL_ERROR` | Check saved request state and resource history before deciding to retry a mutation. |
| 503 | `ACTION_RESULT_UNAVAILABLE` | The action ran but request-result persistence could not be confirmed. Poll the same action and requestId and inspect resource history before starting another write. |
| 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": ["subtitles:write"]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.