{
"openapi": "3.0.0",
"info": {
"title": "AI Video Face Swap",
"description": "# Overview\nVideo face swapping is an AI-powered process that uses YouCam’s AI Video Face Swap API to replace one person's face with another in a video.\nWith advanced AI technology, the AI video face swap delivers remarkably realistic results. The facial expressions, lighting, and skin tones are finely tuned to ensure that the swapped faces blend seamlessly with the original footage.\n\n> **Note:** This API supports video with single face only. For customizable solution, please [contact us](mailto:YouCamOnlineEditor_API@perfectcorp.com).\n\nSample usage cases:\n\n\n\n\n\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n| AI Video Face Swap | The input video must not exceed 30 seconds, 4K resolution, or 30 FPS, and the output is limited to 1280 long-side resolution, 30 FPS, and up to 30 seconds. | Length limit: 30s | container: mov, mp4
video: MPEG-4, MPEG-4 AVC,
audio: aac, amr, mp3 |\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| error_download_video | Download source video error |\n| error_decode_video | Decode source video error |\n| error_unsupported_video | Unsupported video format |\n| exceed_max_filesize | Input file size exceeds the maximum limit|\n| error_nsfw_content_detected | NSFW content detected in the source file |\n| error_decode_mask | Decode mask image error |\n| invalid_parameter | Invalid parameter value|\n\n---\n\n## Unit Consumption\n\n| AI Feature | Unit Consumed |\n|---|---|\n| AI Video Face Swap V1.0 | 1 (5 seconds) * |\n\n > *If the number of images or video duration isn’t evenly divisible, units round up.\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 Face Swap (video) API allows you to swap faces between a target video and one or more reference images using AI technology."
}
],
"paths": {
"/s2s/v2.0/task/face-swap-vid": {
"post": {
"summary": "Run an AI Face Swap (video) task.",
"description": "AI tasks are asynchronous. Prefer webhook-based completion handling when the feature supports webhooks. Configure your webhook endpoint, verify webhook signatures, and use the received `task_id` to query the task result after a `success` or `error` notification. See the [webhook integration guide](/develop/webhook.md) for setup and verification details.\n\nIf webhooks are not supported or cannot be used in your integration, implement polling. After submitting an AI task, poll the status endpoint at regular intervals (e.g., every 10 seconds) until the task status is `success` or `error`.\n",
"tags": [
"V1.0"
],
"security": [
{
"BearerAuthenticationV2": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"anyOf": [
{
"allOf": [
{
"title": "Run task with src file url & ref file url",
"required": [
"ref_file_url"
]
},
{
"$ref": "#/components/schemas/BasicRunTaskV2VidSrcFileUrl"
},
{
"$ref": "#/components/schemas/BasicRunTaskV2RefFileUrl"
}
]
},
{
"allOf": [
{
"title": "Run task with src file url & ref file ID",
"required": [
"ref_file_id"
]
},
{
"$ref": "#/components/schemas/BasicRunTaskV2VidSrcFileUrl"
},
{
"$ref": "#/components/schemas/BasicRunTaskV2RefFileId"
}
]
},
{
"allOf": [
{
"title": "Run task with src file ID & ref file url",
"required": [
"ref_file_url"
]
},
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
},
{
"$ref": "#/components/schemas/BasicRunTaskV2RefFileUrl"
}
]
},
{
"allOf": [
{
"title": "Run task with src file ID & ref file ID",
"required": [
"ref_file_id"
]
},
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
},
{
"$ref": "#/components/schemas/BasicRunTaskV2RefFileId"
}
]
}
]
},
{
"type": "object",
"required": [
"dst_duration"
],
"properties": {
"dst_duration": {
"type": "integer",
"description": "The length of video in seconds"
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "Successful execution of the task",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BasicRunTaskResponseV2"
}
}
}
},
"400": {
"description": "Failed execution of task",
"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": "Check the status of the AI Face Swap (video) task.",
"tags": [
"V1.0"
],
"security": [
{
"BearerAuthenticationV2": []
}
],
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
},
"description": "ID of task to check"
}
],
"responses": {
"200": {
"description": "Successful check of the task status",
"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": "Use the standard 'Bearer authentication'. Put your 'API Key' in header: `Authorization:Bearer YOUR_API_KEY`. Notice that there is ' ' a space between 'Bearer' and the 'YOUR_API_KEY'."
}
},
"schemas": {
"BasicRunTaskV2VidSrcFileUrl": {
"type": "object",
"required": [
"src_file_url"
],
"properties": {
"src_file_url": {
"type": "string",
"description": "Url of the file to run task. The url should be publicly accessible.",
"example": "https://example.com/cat_video.mp4"
}
}
},
"BasicRunTaskV2RefFileUrl": {
"type": "object",
"properties": {
"ref_file_url": {
"type": "string",
"description": "Url of the reference file to run task. The url should be publicly accessible.",
"example": "https://example.com/accessory.jpg"
}
}
},
"BasicRunTaskV2RefFileId": {
"type": "object",
"properties": {
"ref_file_id": {
"type": "string",
"description": "ID of the reference file to run task. File ID from upload file API.",
"example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="
}
}
},
"BasicRunTaskV2SrcFileId": {
"type": "object",
"required": [
"src_file_id"
],
"properties": {
"src_file_id": {
"type": "string",
"description": "ID of file to run task. File ID from upload file API.",
"example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="
}
}
},
"BasicRunTaskResponseV2": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Response status",
"example": 200
},
"data": {
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "ID of this task. Task result is valid to query by this ID for 24 hours.",
"example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
}
}
}
}
},
"RunError": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Response status",
"example": 400
},
"error": {
"type": "string",
"description": "Error message",
"example": "The operation could not be completed"
},
"error_code": {
"type": "string",
"enum": [
"InvalidParameters",
"CreditInsufficiency",
"InvalidStyleGroup",
"InvalidStyle",
"BadRequest"
],
"description": "Error code:\n * InvalidParameters - Invalid request parameters\n * CreditInsufficiency - Insufficient unit to run\n * BadRequest - Unexpected request parameter\n * InvalidStyleGroup - Invalid style group id\n * InvalidStyle - Invalid style id\n"
}
}
},
"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": "Errors:\n- \\`error_exceed_max_image_size\\` - Input image size exceeds the maximum limit\n- \\`exceed_max_filesize\\` - Input file size exceeds the maximum limit\n- \\`invalid_parameter\\` - Invalid parameter value\n- \\`error_download_image\\` - Download source image error\n- \\`error_download_mask\\` - Download mask image error\n- \\`error_decode_image\\` - Decode source image error\n- \\`error_decode_mask\\` - Decode mask image error\n- \\`error_nsfw_content_detected\\` - NSFW content detected in source image\n- \\`error_no_face\\` - No face detected on source image\n- \\`error_pose\\` - Failed to detect pose on source image\n- \\`error_face_parsing\\` - Failed to do face segmentation on source image\n- \\`error_inference\\` - Inference pipeline error\n- \\`exceed_nsfw_retry_limits\\` - Exceed the retry limits to avoid generated NSFW image\n- \\`error_upload\\` - Upload result image error\n- \\`unknown_internal_error\\` - Others\n"
},
"VidTaskStatusResponseBodySingleUrlResultsV2": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "URL to download this result. Valid for 2 hours",
"example": "https://example.com/sample-result-url"
}
}
},
"VidTaskStatusResponseV2": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "Response status",
"example": 200
},
"data": {
"type": "object",
"properties": {
"task_status": {
"type": "string",
"enum": [
"running",
"success",
"error"
],
"description": "Status of this task"
},
"error": {
"$ref": "#/components/schemas/EngineErrorCode"
},
"error_message": {
"type": "string",
"description": "Detailed description of error"
},
"results": null
}
}
},
"$ref": "#/components/schemas/VidTaskStatusResponseBodySingleUrlResultsV2"
}
},
"responses": {
"InvalidApiKey": {
"description": "Invalid or missing API key",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 401,
"description": "Response status"
},
"error": {
"type": "string",
"example": "Invalid API key"
}
}
}
}
}
},
"TooManyRequests": {
"description": "Too many requests",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 429,
"description": "Response status"
},
"error": {
"type": "string",
"example": "Too many requests"
}
}
}
}
}
},
"InvalidTaskId": {
"description": "Invalid task ID",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 400,
"description": "Response status"
},
"error": {
"type": "string",
"example": "Invalid task ID"
}
}
}
}
}
},
"TaskTimeout": {
"description": "Task execution timeout",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 500,
"description": "Response status"
},
"error": {
"type": "string",
"example": "Task execution timed out"
}
}
}
}
}
}
}
}
}