{ "openapi": "3.0.0", "info": { "title": "AI 動画顔入れ替え", "description": "# 概要\n動画顔入れ替えは、YouCam の AI 動画顔入れ替え API で、動画内の人物の顔を別の人物の顔に置き換える AI 駆動のプロセスです。\n高度な AI 技術により、AI 動画顔入れ替えは非常にリアルな結果を提供します。顔の表情、ライティング、肌色は細かく調整され、入れ替えた顔が元の映像とシームレスに融合するようにします。\n\n> **備考:** この API は単一の顔を含む動画のみをサポートします。カスタマイズ可能なソリューションについては、[お問い合わせください](mailto:YouCamOnlineEditor_API@perfectcorp.com)。\n\n使用例:\n![](https://plugins-media.makeupar.com/smb/blog/post/2024-08-23/b1f96100-37d6-4c28-b467-d397e9c3a25d.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/dt_yce_video_face_swap_S3_video_03_28785ebe0c.jpg)\n\n![](https://plugins-media.makeupar.com/smb/story/2024-09-12/3582f617-e88e-4219-9e72-43d4c26791cd.png)\n\n---\n\n## ファイル仕様とエラー\n\n* 対応フォーマットと寸法\n\n|AI 機能|対応寸法|対応ファイルサイズ|対応フォーマット|\n| ---- | ---- | ---- | ---- |\n| AI 動画顔入れ替え | 入力動画は 30 秒、4K 解像度、または 30 FPS を超えてはならず、出力は長辺 1280 解像度、30 FPS、最大 30 秒に制限されます。 | 長さ制限: 30s | コンテナ: mov, mp4
動画: MPEG-4, MPEG-4 AVC,
音声: aac, amr, mp3 |\n\n* エラーコード\n\n|エラーコード|説明|\n| ---- | ---- |\n| error_download_video | ソース動画のダウンロードに失敗しました |\n| error_decode_video | ソース動画のデコードに失敗しました |\n| error_unsupported_video | 対応していない動画形式です |\n| exceed_max_filesize | 入力ファイルサイズが最大制限を超えています|\n| error_nsfw_content_detected | ソースファイルで NSFW コンテンツが検出されました |\n| error_decode_mask | マスク画像のデコードに失敗しました |\n| invalid_parameter | パラメータ値が無効です|\n\n---\n\n## ユニット消費量\n\n| AI 機能 | 消費ユニット |\n|---|---|\n| AI 動画顔入れ替え V1.0 | 1 (5 秒) * |\n\n > *画像数または動画の長さが割り切れない場合、ユニットは切り上げられます。\n\n---\n", "version": "", "termsOfService": "https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api", "contact": { "email": "YouCamOnlineEditor_API@perfectcorp.com" }, "license": { "name": "Privacy policy", "url": "https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api" } }, "servers": [ { "url": "https://yce-api-01.makeupar.com" } ], "tags": [ { "name": "V1.0", "description": "AI 顔交換（動画）API を使用すると、AI 技術によりターゲット動画と 1 つ以上の参照画像の間で顔を交換できます。" } ], "paths": { "/s2s/v2.0/task/face-swap-vid": { "post": { "summary": "AI 顔交換（動画）タスクを実行します。", "description": "AI タスクは非同期です。機能ごとに Webhook がサポートされている場合は、Webhook による完了処理を優先します。Webhook エンドポイントを設定し、Webhook 署名を検証したうえで、`success` または `error` の通知が来たら、受け取った `task_id` を使ってタスクの結果を照会します。設定と検証の詳細は [Webhook 統合ガイド](../develop/webhook.md) を参照してください。\n\nWebhook がサポートされていない場合、または統合に使えない場合は、ポーリングを実装します。AI タスクを送信した後、一定の間隔（例：10 秒ごと）でステータスエンドポイントをポーリングし、`success` または `error` になるまで待ちます。\n", "tags": [ "V1.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "anyOf": [ { "allOf": [ { "title": "src ファイル URL と ref ファイル URL でタスクを実行", "required": [ "ref_file_url" ] }, { "$ref": "#/components/schemas/BasicRunTaskV2VidSrcFileUrl" }, { "$ref": "#/components/schemas/BasicRunTaskV2RefFileUrl" } ] }, { "allOf": [ { "title": "src ファイル URL と ref ファイル ID でタスクを実行", "required": [ "ref_file_id" ] }, { "$ref": "#/components/schemas/BasicRunTaskV2VidSrcFileUrl" }, { "$ref": "#/components/schemas/BasicRunTaskV2RefFileId" } ] }, { "allOf": [ { "title": "src ファイル ID と ref ファイル URL でタスクを実行", "required": [ "ref_file_url" ] }, { "$ref": "#/components/schemas/BasicRunTaskV2SrcFileId" }, { "$ref": "#/components/schemas/BasicRunTaskV2RefFileUrl" } ] }, { "allOf": [ { "title": "src ファイル ID と ref ファイル ID でタスクを実行", "required": [ "ref_file_id" ] }, { "$ref": "#/components/schemas/BasicRunTaskV2SrcFileId" }, { "$ref": "#/components/schemas/BasicRunTaskV2RefFileId" } ] } ] }, { "type": "object", "required": [ "dst_duration" ], "properties": { "dst_duration": { "type": "integer", "description": "動画の長さ（秒）" } } } ] } } } }, "responses": { "200": { "description": "タスクの実行に成功しました", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicRunTaskResponseV2" } } } }, "400": { "description": "タスクの実行に失敗しました", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RunError" } ] } } } }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/s2s/v2.0/task/face-swap-vid/{task_id}": { "get": { "summary": "AI 動画顔入れ替えタスクのステータスを確認します。", "tags": [ "V1.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe" }, "description": "確認するタスクの ID" } ], "responses": { "200": { "description": "タスクステータスの確認に成功しました", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VidTaskStatusResponseV2" } } } }, "400": { "$ref": "#/components/responses/InvalidTaskId" }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "500": { "$ref": "#/components/responses/TaskTimeout" } } } } }, "components": { "securitySchemes": { "BearerAuthenticationV2": { "type": "http", "scheme": "bearer", "description": "標準の 'Bearer authentication' を使用します。ヘッダーに `Authorization:Bearer YOUR_API_KEY` の形式で 'API Key' を設定してください。'Bearer' と 'YOUR_API_KEY' の間にスペースがある点にご注意ください。" } }, "schemas": { "BasicRunTaskV2VidSrcFileUrl": { "type": "object", "required": [ "src_file_url" ], "properties": { "src_file_url": { "type": "string", "description": "タスクを実行するファイルの URL。この URL は公開されている必要があります。", "example": "https://example.com/cat_video.mp4" } } }, "BasicRunTaskV2RefFileUrl": { "type": "object", "properties": { "ref_file_url": { "type": "string", "description": "タスクを実行するための参照ファイルの URL。この URL は公開されている必要があります。", "example": "https://example.com/accessory.jpg" } } }, "BasicRunTaskV2RefFileId": { "type": "object", "properties": { "ref_file_id": { "type": "string", "description": "タスクを実行するための参照ファイルの ID。ファイルアップロード API から取得したファイル ID です。", "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=" } } }, "BasicRunTaskV2SrcFileId": { "type": "object", "required": [ "src_file_id" ], "properties": { "src_file_id": { "type": "string", "description": "タスクを実行するファイルの ID。ファイルアップロード API から取得したファイル ID です。", "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=" } } }, "BasicRunTaskResponseV2": { "type": "object", "properties": { "status": { "type": "integer", "description": "レスポンスステータス", "example": 200 }, "data": { "type": "object", "properties": { "task_id": { "type": "string", "description": "このタスクの ID。タスクの結果は、この ID を使用して 24 時間以内にクエリできます。", "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe" } } } } }, "RunError": { "type": "object", "properties": { "status": { "type": "integer", "description": "レスポンスステータス", "example": 400 }, "error": { "type": "string", "description": "エラーメッセージ", "example": "The operation could not be completed" }, "error_code": { "type": "string", "enum": [ "InvalidParameters", "CreditInsufficiency", "InvalidStyleGroup", "InvalidStyle", "BadRequest" ], "description": "エラーコード:\n * InvalidParameters - 無効なリクエストパラメータ\n * CreditInsufficiency - 実行に必要なユニットが不足しています\n * BadRequest - 予期しないリクエストパラメータ\n * InvalidStyleGroup - 無効なスタイルグループ ID\n * InvalidStyle - 無効なスタイル ID" } } }, "EngineErrorCode": { "type": "string", "nullable": true, "enum": [ "error_exceed_max_image_size", "exceed_max_filesize", "invalid_parameter", "error_download_image", "error_download_mask", "error_decode_image", "error_decode_mask", "error_nsfw_content_detected", "error_no_face", "error_pose", "error_face_parsing", "error_inference", "exceed_nsfw_retry_limits", "error_upload", "unknown_internal_error" ], "description": "エラー：\n- `error_exceed_max_image_size` - 入力画像サイズが最大制限を超えています\n- `exceed_max_filesize` - 入力ファイルサイズが最大制限を超えています\n- `invalid_parameter` - 無効なパラメータ値\n- `error_download_image` - ソース画像のダウンロードエラー\n- `error_download_mask` - マスク画像のダウンロードエラー\n- `error_decode_image` - ソース画像のデコードエラー\n- `error_decode_mask` - マスク画像のデコードエラー\n- `error_nsfw_content_detected` - ソース画像で NSFW コンテンツが検出されました\n- `error_no_face` - ソース画像で顔が検出されませんでした\n- `error_pose` - ソース画像でポーズの検出に失敗しました\n- `error_face_parsing` - ソース画像での顔セグメンテーションに失敗しました\n- `error_inference` - 推論パイプラインエラー\n- `exceed_nsfw_retry_limits` - NSFW 画像の生成を避けるための再試行制限を超えました\n- `error_upload` - 結果画像のアップロードエラー\n- `unknown_internal_error` - その他\n" }, "VidTaskStatusResponseBodySingleUrlResultsV2": { "type": "object", "properties": { "url": { "type": "string", "description": "この結果をダウンロードする URL。有効期間は 2 時間です", "example": "https://example.com/sample-result-url" } } }, "VidTaskStatusResponseV2": { "type": "object", "properties": { "status": { "type": "integer", "description": "レスポンスステータス", "example": 200 }, "data": { "type": "object", "properties": { "task_status": { "type": "string", "enum": [ "running", "success", "error" ], "description": "このタスクのステータス" }, "error": { "$ref": "#/components/schemas/EngineErrorCode" }, "error_message": { "type": "string", "description": "エラーの詳細な説明" }, "results": null } } }, "$ref": "#/components/schemas/VidTaskStatusResponseBodySingleUrlResultsV2" } }, "responses": { "InvalidApiKey": { "description": "無効または欠落している API キー", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 401, "description": "レスポンスステータス" }, "error": { "type": "string", "example": "Invalid API key" } } } } } }, "TooManyRequests": { "description": "リクエストが多すぎます", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 429, "description": "レスポンスステータス" }, "error": { "type": "string", "example": "Too many requests" } } } } } }, "InvalidTaskId": { "description": "無効なタスク ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 400, "description": "レスポンスステータス" }, "error": { "type": "string", "example": "Invalid task ID" } } } } } }, "TaskTimeout": { "description": "タスク実行タイムアウト", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 500, "description": "レスポンスステータス" }, "error": { "type": "string", "example": "Task execution timed out" } } } } } } } } }