> ## 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.
# プロジェクトを作成して文字起こし
> アップロード済みの fileKey からプロジェクトを作成し、文字起こしします。保存されたメディアから長さとファイルサイズを確認します。任意の webhookUrl で処理イベントを受信できます。projects_status で状態を確認してください。
アップロード済みの fileKey からプロジェクトを作成し、文字起こしします。保存されたメディアから長さとファイルサイズを確認します。任意の webhookUrl で処理イベントを受信できます。projects\_status で状態を確認してください。
```http theme={null}
POST https://api.voicecheap.ai/v1/actions/projects_create
```
## 認証と権限
このヘッダーに VoiceCheap API キーを指定してください。同じ API キーを Authorization: Bearer で送信することもできます。OAuth アクセストークンは MCP
でのみ使用でき、この REST エンドポイントでは使用できません。
必要な権限: `projects:write`, `transcription:write`.
有効な有料サブスクリプションが必要です。権限によってチーム内のロール、リソースの所有権、メディアクレジット、プランの制限が変わることはありません。
## パラメーター
テキスト値。
最小文字数: 1. 最大文字数: 1024.
テキスト値。
許容値: "afrikaans", "albanian", "amharic", "arabic", "armenian", "assamese", "azerbaijani", "basque", "belarusian", "bengali", "bosnian", "bulgarian", "catalan", "croatian", "czech", "danish", "dutch", "english", "british english", "estonian", "finnish", "french", "french canadian", "galician", "german", "greek", "gujarati", "hebrew", "hindi", "hungarian", "icelandic", "indonesian", "irish", "italian", "japanese", "kannada", "kazakh", "khmer", "korean", "lao", "latvian", "lithuanian", "macedonian", "malay", "malayalam", "mandarin", "marathi", "mongolian", "nepali", "norwegian", "persian", "polish", "portuguese", "brazilian portuguese", "pt\_brazil", "punjabi", "romanian", "russian", "serbian", "slovak", "slovenian", "spanish", "swahili", "swedish", "tagalog", "tamil", "telugu", "thai", "turkish", "ukrainian", "urdu", "vietnamese", "welsh", "yoruba", "zulu".
テキスト値。
許容値: "af", "sq", "am", "ar", "hy", "as", "ast", "az", "ba", "eu", "be", "bn", "bs", "br", "bg", "my", "ca", "ceb", "zh", "hr", "cs", "da", "nl", "en", "eo", "at", "et", "fil", "fo", "fi", "fr", "fr-CA", "fy", "ff", "gd", "gl", "lg", "ka", "de", "el", "gu", "ht", "ha", "haw", "he", "hi", "hu", "is", "ig", "ilo", "id", "ia", "ga", "it", "ja", "jv", "kea", "kn", "kk", "km", "kur", "kir", "ko", "lo", "la", "luo", "lv", "lb", "ln", "lt", "mk", "mg", "ms", "ml", "mt", "mi", "mr", "mo", "mn", "ne", "no", "nn", "nso", "nya", "oc", "or", "pa", "ps", "fa", "pl", "pt", "ro", "ru", "sa", "sr", "sn", "sd", "si", "sk", "sl", "so", "es", "su", "sw", "ss", "sv", "tl", "tg", "ta", "tt", "te", "th", "bo", "tn", "tr", "tk", "ug", "uk", "umb", "ur", "uz", "vi", "cy", "wo", "xh", "yi", "yo", "zu", "cmn", "yue", "en-GB", "en-US", "en-AU", "auto-detect".
テキスト値。
最小文字数: 1. 最大文字数: 200.
テキスト値。
許容値: "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "auto-detect".
値のリスト。要素の構造は完全な入力スキーマを参照してください。
最大要素数: 1000.
真偽値。
テキスト値。
最大文字数: 1000000.
テキスト値。
最大文字数: 2048. 形式: "uri".
トランスポート境界では任意です。省略すると、検証前にサーバーが識別子を補完します。レスポンスを受信できなかった場合に安全に復旧できるよう、固定の UUID v4 を指定してください。
形式: "uuid". パターン: `^[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}$`.
以下の JSON Schema は、ディスカバリーで公開される正確なフィールド名、ネストされた型、デフォルト値、範囲、許容値を保持しています。フィールド間の追加ルールは操作の注意事項に記載されています。
```json theme={null}
{
"type": "object",
"properties": {
"fileKey": {
"type": "string",
"minLength": 1,
"maxLength": 1024
},
"targetLanguage": {
"type": "string",
"enum": [
"afrikaans",
"albanian",
"amharic",
"arabic",
"armenian",
"assamese",
"azerbaijani",
"basque",
"belarusian",
"bengali",
"bosnian",
"bulgarian",
"catalan",
"croatian",
"czech",
"danish",
"dutch",
"english",
"british english",
"estonian",
"finnish",
"french",
"french canadian",
"galician",
"german",
"greek",
"gujarati",
"hebrew",
"hindi",
"hungarian",
"icelandic",
"indonesian",
"irish",
"italian",
"japanese",
"kannada",
"kazakh",
"khmer",
"korean",
"lao",
"latvian",
"lithuanian",
"macedonian",
"malay",
"malayalam",
"mandarin",
"marathi",
"mongolian",
"nepali",
"norwegian",
"persian",
"polish",
"portuguese",
"brazilian portuguese",
"pt_brazil",
"punjabi",
"romanian",
"russian",
"serbian",
"slovak",
"slovenian",
"spanish",
"swahili",
"swedish",
"tagalog",
"tamil",
"telugu",
"thai",
"turkish",
"ukrainian",
"urdu",
"vietnamese",
"welsh",
"yoruba",
"zulu"
]
},
"originalLanguage": {
"type": "string",
"enum": [
"af",
"sq",
"am",
"ar",
"hy",
"as",
"ast",
"az",
"ba",
"eu",
"be",
"bn",
"bs",
"br",
"bg",
"my",
"ca",
"ceb",
"zh",
"hr",
"cs",
"da",
"nl",
"en",
"eo",
"at",
"et",
"fil",
"fo",
"fi",
"fr",
"fr-CA",
"fy",
"ff",
"gd",
"gl",
"lg",
"ka",
"de",
"el",
"gu",
"ht",
"ha",
"haw",
"he",
"hi",
"hu",
"is",
"ig",
"ilo",
"id",
"ia",
"ga",
"it",
"ja",
"jv",
"kea",
"kn",
"kk",
"km",
"kur",
"kir",
"ko",
"lo",
"la",
"luo",
"lv",
"lb",
"ln",
"lt",
"mk",
"mg",
"ms",
"ml",
"mt",
"mi",
"mr",
"mo",
"mn",
"ne",
"no",
"nn",
"nso",
"nya",
"oc",
"or",
"pa",
"ps",
"fa",
"pl",
"pt",
"ro",
"ru",
"sa",
"sr",
"sn",
"sd",
"si",
"sk",
"sl",
"so",
"es",
"su",
"sw",
"ss",
"sv",
"tl",
"tg",
"ta",
"tt",
"te",
"th",
"bo",
"tn",
"tr",
"tk",
"ug",
"uk",
"umb",
"ur",
"uz",
"vi",
"cy",
"wo",
"xh",
"yi",
"yo",
"zu",
"cmn",
"yue",
"en-GB",
"en-US",
"en-AU",
"auto-detect"
]
},
"projectName": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"numberOfSpeakers": {
"type": "string",
"enum": [
"1",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9",
"10",
"11",
"12",
"13",
"14",
"15",
"16",
"17",
"18",
"19",
"20",
"21",
"22",
"23",
"24",
"25",
"26",
"27",
"28",
"29",
"30",
"31",
"32",
"auto-detect"
]
},
"brandVocabulary": {
"maxItems": 1000,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200
}
},
"removeFillerWords": {
"type": "boolean"
},
"sourceSrt": {
"type": "string",
"maxLength": 1000000
},
"webhookUrl": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"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": ["fileKey", "targetLanguage"],
"additionalProperties": false
}
```
## 冪等性
変更操作ごとに、requestId または Idempotency-Key HTTP ヘッダーに UUID v4 を指定してください。ネットワーク障害後の再試行では、同じ識別子と同一の引数を使用します。両方を指定する場合は一致させる必要があります。保存済みリクエストを再取得しても、操作は再実行されず、月間呼び出し回数も追加で消費されません。失敗または中断したリクエストは自動的には再開されません。
すべての変更操作は、再試行時に同じリクエストがまだ実行中であれば、通常の初回実行が同期処理であっても HTTP 202 を返す場合があります。実行が完了していても resultStored が false の場合、再試行では元の結果ではなく、保存済みリクエストの状態を HTTP 200 で返します。出力は対応するドメインの履歴、結果、またはダウンロードアクションで取得してください。
## リクエスト例
例に記載されたリソース識別子とメディアキーを、ご自身のアカウントで返された値に置き換えてください。同じ変更操作を再試行する場合は、リクエスト識別子を変更しないでください。
```bash cURL theme={null}
curl --request POST 'https://api.voicecheap.ai/v1/actions/projects_create' \
--header "x-api-key: $VOICECHEAP_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"fileKey":"uploads/your-user-id/6bee76be-109f-423a-88fb-f41e2aa1f03b-launch.mp4","targetLanguage":"english","originalLanguage":"fr","projectName":"Product launch","numberOfSpeakers":"auto-detect","brandVocabulary":["VoiceCheap"],"removeFillerWords":true,"requestId":"41321bda-e243-4b6f-96a4-622cd047c991"}'
```
```javascript JavaScript theme={null}
const input = {
fileKey: 'uploads/your-user-id/6bee76be-109f-423a-88fb-f41e2aa1f03b-launch.mp4',
targetLanguage: 'english',
originalLanguage: 'fr',
projectName: 'Product launch',
numberOfSpeakers: 'auto-detect',
brandVocabulary: ['VoiceCheap'],
removeFillerWords: true,
requestId: '41321bda-e243-4b6f-96a4-622cd047c991',
};
const response = await fetch('https://api.voicecheap.ai/v1/actions/projects_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/projects_create",
headers={"x-api-key": os.environ["VOICECHEAP_API_KEY"]},
json={"fileKey": "uploads/your-user-id/6bee76be-109f-423a-88fb-f41e2aa1f03b-launch.mp4", "targetLanguage": "english", "originalLanguage": "fr", "projectName": "Product launch", "numberOfSpeakers": "auto-detect", "brandVocabulary": ["VoiceCheap"], "removeFillerWords": True, "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)
```
## レスポンス
初回実行が成功すると、操作結果を data に格納して HTTP 200 を返します。同じリクエストを再送した場合は、代わりに保存済みリクエストの状態を返すことがあります。例はサポートされるレスポンスの一例であり、すべての任意フィールドを示すものではありません。
文字起こしの開始直後に、新しいプロジェクトの識別情報を返します。翻訳の開始や完了済みの文字起こしの返却は行いません。
```json HTTP 200 theme={null}
{
"data": {
"success": true,
"message": "Project created. Transcription started.",
"projectId": "project_launch_2026",
"projectName": "Product launch",
"targetLanguage": "english",
"status": "processing"
},
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991"
}
```
```json HTTP 202 replay_running theme={null}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "projects_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": "projects_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"
}
```
## 結果フィールド
| フィールド | 説明 |
| - | - |
| `data.success` | プロジェクトの作成とパイプラインへの受け入れが成功した場合は True。 |
| `data.message` | プロジェクト作成の受け付け確認。 |
| `data.projectId` | 新しいプロジェクトの識別子。 |
| `data.projectName` | 指定したプロジェクト名。名前を指定しなかった場合は、新しいプロジェクトの識別子。 |
| `data.targetLanguage` | 作成時に選択する必須の対象言語。 |
| `data.status` | processing。このレスポンスの後も文字起こしは続きます。 |
## リクエストの復旧とポーリング
接続が切断された後も同じ識別子を使用してください。resultStored が false の場合は、対応する履歴、結果、またはダウンロードアクションで出力を取得します。進捗を確認するためだけに、別の生成を開始しないでください。
```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":"projects_create"}'
```
```json HTTP 200 theme={null}
{
"data": {
"requestId": "41321bda-e243-4b6f-96a4-622cd047c991",
"operation": "projects_create",
"status": "completed",
"createdAt": 1792144800000,
"updatedAt": 1792144820000,
"resultStored": true,
"result": {
"success": true,
"message": "Project created. Transcription started.",
"projectId": "project_launch_2026",
"projectName": "Product launch",
"targetLanguage": "english",
"status": "processing"
}
}
}
```
## 操作の注意事項
* 先にメディアをアップロードまたはインポートし、認証済みの実行者が所有する完了済み fileKey を渡してください。長さ、MIME タイプ、バイト数は保存されたオブジェクトから測定され、呼び出し元が指定できる入力フィールドではありません。
* 文字起こしのみを行うアクションですが、targetLanguage は必須です。元の文字起こしが完了した後に translations\_start または translations\_dub を使用してください。
* sourceSrt は原文の文字起こしテキストを置き換え、originalLanguage の明示指定が必要です。brandVocabulary は検証され、未指定の場合はアカウントの保存済み語彙が使用されます。
* webhookUrl は、コールバック先を上書きする任意の公開 HTTPS URL です。プライベートネットワークや安全でない宛先は拒否されます。
* projects\_status をポーリングし、その後 transcripts\_get で文字起こしを取得してください。この結果の processing ステータスは、メディアのワークフローを表します。
* originalLanguage には fr や en などの元言語コード（対応する場合は auto-detect）を指定します。targetLanguage には english などの対応する翻訳先言語名を指定します。
## 使用量
正常に実行された呼び出しごとに、月間 API/MCP 呼び出し回数を 1 回消費します。メディアクレジットと、その操作固有の生成枠も適用されます。
## エラー
| HTTP ステータス | コード | 意味または対処方法 |
| - | - | - |
| 400 | `CREDENTIAL_IN_QUERY` | access\_token または api\_key クエリパラメーターに認証情報が指定されています。認証情報はヘッダーで送信してください。 |
| 400 | `FILE_TOO_LARGE` | 保存済みのアップロードが、アカウントのアップロードサイズ上限を超えています。 |
| 400 | `IDEMPOTENCY_CONFLICT` | Idempotency-Key ヘッダーとリクエストボディの requestId は一致させる必要があります。 |
| 400 | `INVALID_FILE_TYPE` | アップロードしたファイル名に、対応する音声または動画の拡張子がありません。 |
| 400 | `INVALID_MEDIA_DURATION` | 計測した長さが無効か、プランの上限を超えています。 |
| 400 | `INVALID_REQUEST_ID` | UUID v4 の requestId または Idempotency-Key を指定してください。 |
| 400 | `INVALID_SOURCE_SRT` | sourceSrt は有効なSRTキューを含む必要があります。 |
| 400 | `SOURCE_LANGUAGE_REQUIRED_FOR_SRT` | sourceSrt を指定する場合は、originalLanguage を明示的に設定してください。 |
| 400 | `VALIDATION_ERROR` | スキーマに従って入力を修正してください。無効な値や整合性のない値は実行前に拒否されます。 |
| 401 | `API_KEY_EXPIRED` | API キーの有効期限が切れています。 |
| 401 | `INVALID_API_KEY` | 有効期限内の有効な API キーを指定してください。 |
| 401 | `INVALID_CREDENTIAL` | Authorization ヘッダーの形式が不正、または x-api-key と競合しています。 |
| 401 | `MISSING_CREDENTIAL` | 利用可能なヘッダー認証情報が指定されていないか、4096文字を超えています。 |
| 401 | `USER_NOT_FOUND` | 認証情報に対応するアカウントはすでに存在しません。 |
| 403 | `ACCOUNT_UNAVAILABLE` | 操作を実行するアカウントまたは請求対象アカウントが利用できないか、削除中です。 |
| 403 | `AMBIGUOUS_TEAM_API_KEY` | 認証情報のユーザーが複数のチームに属しているため、課金コンテキストが曖昧です。 |
| 403 | `INSUFFICIENT_SCOPE` | 必要な権限をすべて付与するか、別の認証情報を使用してください。 |
| 403 | `INTEGRATION_PLAN_UNSUPPORTED` | アカウントの連携上限を確認できませんでした。 |
| 403 | `INVALID_FILE_REFERENCE` | fileKey は、認証済み実行者が所有する completed のアップロードを示す必要があります。 |
| 403 | `SUBSCRIPTION_REQUIRED` | 有効な有料サブスクリプションを使用してください。 |
| 403 | `TEAM_OWNER_NOT_FOUND` | 実効的なチームオーナーのアカウントが見つかりませんでした。 |
| 404 | `MEDIA_NOT_FOUND` | アップロードしたオブジェクトが存在しないか、空です。 |
| 409 | `CONCURRENT_ACTION_LIMIT_REACHED` | このアカウントでは、すでに 10 件の連携アクションが実行中です。新しいアクションを開始する前に、既存のリクエストをポーリングしてください。 |
| 409 | `IDEMPOTENCY_CONFLICT` | 識別子を再利用する場合は、同じ操作と引数でのみ使用してください。 |
| 429 | `CONCURRENT_TRANSLATION_LIMIT_REACHED` | このアカウントは、すでに API 翻訳の同時実行数上限に達しています。 |
| 429 | `INTEGRATION_MONTHLY_LIMIT_REACHED` | 月次リセットを待つか、プランを変更してください。 |
| 429 | `INTEGRATION_RATE_LIMIT_REACHED` | Retry-After がある場合は指定時間を待ち、バックオフを使用してください。 |
| 500 | `INTERNAL_ERROR` | 変更操作を再試行するか判断する前に、保存済みリクエストの状態とリソースの履歴を確認してください。 |
| 503 | `ACTION_RESULT_UNAVAILABLE` | アクションは実行されましたが、結果を保存できませんでした。新しい生成を開始する前に、保存済みリクエストの状態とリソース履歴を確認してください。 |
| 503 | `SERVER_RESTARTING` | サーバーが再起動中です。少し待ってから再試行し、変更操作では同じリクエスト識別子を使用してください。 |
```json theme={null}
{
"code": "INSUFFICIENT_SCOPE",
"message": "This credential does not permit the requested action.",
"status": 403,
"details": {
"requiredScopes": ["projects:write", "transcription:write"]
}
}
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.