Introducing the DeepFace Video API, which utilizes a neural network to swap faces in video content. This feature is accessible for incorporation into various applications and projects through the Yes Ai API. Leverage our API to develop services that offer facial replacement capabilities. We advise performing initial trials using our Telegram bot @yes_ai_bot before full-scale implementation.
Accessing the API requires a unique authorization token. Detailed instructions on how to acquire this token are provided within this document.
How to Upload a New Task for Face Replacement in a DeepFace Video Using the Yes Ai API
POST https://api.yesai.su/v2/yesvideo/aniphoto/deepface
headers: { Content-Type: application/json , Authorization: Bearer <token> }
Example request for submitting a DeepFace Video job
curl -X POST https://api.yesai.su/v2/yesvideo/aniphoto/deepface
-H "Authorization: Bearer <token>"
-H "Content-Type: application/json"
-d '{
"photo_url": "https://yoururl.com/face1.jpeg",
"video_url": "https://yoururl.com/video1.mp4"
}'Parameters:
photo_url = '...' (required, link to photo in https format ://... )
video_url = '...' (required, link to the video in the format https://... )
List of possible errors:
['success' => false, 'message' => 'PHOTO_URL_IS_EMPTY'], 400
['success' => false, 'message' => 'PHOTO_URL_NOT_VALID'], 400
['success' => false, 'message' => 'VIDEO_URL_IS_EMPTY'], 400
['success' => false, 'message' => 'VIDEO_URL_NOT_VALID'], 400
['success' => false, 'message' => 'PHOTO_FILE_SIZE_NOT_VALID'], 400
['success' => false, 'message' => 'VIDEO_FILE_SIZE_NOT_VALID'], 400
['success' => false, 'message' => 'PHOTO_MIME_TYPE_NOT_VALID'], 400
['success' => false, 'message' => 'VIDEO_MIME_TYPE_NOT_VALID'], 400
['success' => false, 'message' => 'UNAUTHORIZED'], 401
['success' => false, 'message' => 'PHOTO_NOT_FOUND'], 404
['success' => false, 'message' => 'VIDEO_NOT_FOUND'], 404
['success' => false, 'message' => 'NOT_ENOUGH_RPOINTS'], 409
['success' => false, 'message' => 'TASK_LIMIT_EXCEEDED'], 409
['success' => false, 'message' => 'TOO_MANY_REQUESTS'], 429
['success' => false, 'message' => 'INTERNAL_SERVER_ERROR'], 500
Response format for successful submission of a new task:
['success' = > true, 'message' => 'OK', 'results' => ['animation_data' => [ ... ]]], 200
Once you have successfully submitted the task, you will be provided with a distinctive identification number "id" that you can use subsequently to verify the status of your task completion.
Verify the progress of a specific task using its identification number
GET https://api.yesai.su/v2/yesvideo/animations/{id}
headers: { Content-Type: application /json, Authorization: Bearer <token> }
An example of a request to obtain the execution status of one DeepFace Video task
curl -X GET https://api.yesai.su/v2/yesvideo/animations/{id}
-H "Authorization: Bearer <token>"
-H "Content-Type: application/json"Parameters:
{id} = 12345 (required, task id)
Possible errors:
['success' => false, 'message' => 'ID_IS_EMPTY'], 400
['success' => false, 'message' => 'ID_NOT_VALID'], 400
['success' => false, 'message' => 'ID_NOT_FOUND'], 404
['success' => false, 'message' => 'UNAUTHORIZED'], 401
['success' => false, 'message' => 'TOO_MANY_REQUESTS'], 429
['success' => false, 'message' => 'INTERNAL_SERVER_ERROR'], 500
Format for confirming the successful verification of task completion status:
['success' => true, 'message' => 'OK', 'results' => ['animation_data' => [ ... ]]], 200
Possible status codes:
"status": 0 ("status_description":"waiting in line") - the task is awaiting its turn (patience is required)
"status": 1 ("status_description":"currently processing") - the task is currently being processed (a little more patience is needed)
"status": 2 ("status_description":"finished successfully") - the task has been successfully finished (the results are ready for review)
"status": 3 ("status_description":"error led to rejection") - the task has been rejected due to an error (examine the error details in the “comment_ru” and “comment_en” sections)
"status": 4 ("status_description":"rejected for exceeding time limit") - the task has been rejected for taking too long (consider resubmitting the task)
Examining the Completion Status of a Batch of Recent Tasks
This approach to monitoring job progress is ideal when you're overseeing tasks collectively instead of on a one-by-one basis. The outcome of this inquiry will be a compilation of the latest 20 tasks, each reflecting the status you've chosen.
Absent a specified status filter in the inquiry, the endpoint will generate an enumeration of the 20 most recent tasks.
GET https://api.yesai.su/v2/yesvideo/animations?type=13&status={status}
headers: { Content-Type : application/json, Authorization: Bearer <token> }
An example of a request to get the execution status of the latest DeepFace Video jobs
curl -X GET https://api.yesai.su/v2/yesvideo/animations?type=13&status={status}
-H "Authorization: Bearer <token>"
-H "Content-Type: application/json"Parameters:
{status} = 2 (required, task status. It is allowed to list several types of statuses in one request, separated by commas, for example: status=1,2,3)
{type} = 13 (required, service type DeepFace Video)
The {status} parameter can take the following values:
0 - list of tasks that are in the queue for execution
1 - list of tasks that are already running
2 - list of tasks that have already been completed
3 - list of tasks that are rejected by the system
4 - list of jobs that are rejected due to timeout
Possible errors:
['success' => false, 'message' => 'TYPE_IS_EMPTY'], 400
['success' => false, 'message' => 'TYPE_NOT_VALID'], 400
['success' => false, 'message' => 'TYPES_NOT_VALID'], 400
['success' => false, 'message' => 'STATUS_IS_EMPTY'], 400
['success' => false, 'message' => 'STATUS_NOT_VALID'], 400
['success' => false, 'message' => 'LIMIT_OFFSET_IS_EMPTY'], 400
['success' => false, 'message' => 'LIMIT_OFFSET_NOT_VALID'], 400
['success' => false, 'message' => 'LIMIT_COUNT_IS_EMPTY'], 400
['success' => false, 'message' => 'LIMIT_COUNT_NOT_VALID'], 400
['success' => false, 'message' => 'SORT_FIELD_IS_EMPTY'], 400
['success' => false, 'message' => 'SORT_FIELD_NOT_VALID'], 400
['success' => false, 'message' => 'SORT_ORDER_IS_EMPTY'], 400
['success' => false, 'message' => 'SORT_ORDER_NOT_VALID'], 400
['success' => false, 'message' => 'DATA_TYPE_IS_EMPTY'], 400
['success' => false, 'message' => 'DATA_TYPE_NOT_VALID'], 400
['success' => false, 'message' => 'ID_OFFSET_IS_EMPTY'], 400
['success' => false, 'message' => 'ID_OFFSET_NOT_VALID'], 400
['success' => false, 'message' => 'UNAUTHORIZED'], 401
['success' => false, 'message' => 'TOO_MANY_REQUESTS'], 429
['success' => false, 'message' => 'INTERNAL_SERVER_ERROR'], 500
A sample output in JSON structure for verifying the current state of a task.
Example API response when requesting DeepFace Video job status
{
"success": true, // data received successfully
"message": "OK",
"results": {
"animation_data": {
"id": 1, // unique task ID in the Yes Ai system
"user_id": 1, // ID of the user who submitted the task
"tariff_id": 30, // user tariff plan (0 - Demo, 5 - Micro, 10 - Start, 20 - Standard, 30 - VIP)
"type": 13, // type of task completed, 13 - DeepFace Video
"photo_url": "https://yourdomain.com/face1.jpeg", // link with the original photo from which the face was taken to replace it in the video
"audio_url": "", // in this type of task the variable is not used
"video_url": "https://yourdomain.com/video1.mp4", // original video in which you need to replace the face
"result_url": "https://yesai.su/files/video/1_1234567890.mp4", // the result of the task is in MP4 format, you need to download it to your server
"result_type": "video", // the file type for the completed task, for DeepFace Video it is always 'video'
"result_data": {
"video_width": 672, // width of the video in pixels that is the result of the job
"video_height": 1280, // height of the video in pixels that is the result of the job
"video_duration": 17, // video duration in seconds
"video_durrange": 0, // variable is not used in this job type
"video_fps": 60 // number of frames per second
},
"comment_ru": "", // comment for the task in Russian, it is filled in only if the task could not be completed
"comment_en": "", // comment for the task in English, it is filled in only if the task could not be completed
"accounting": {
"total_cost": 35.094528, // total cost of completing the task in conventional units
"spent_points": 0, // the number of ⭐️points that were removed from the balance for completing the task. For DeepFace Video, the field will always be 0, because payment is made in 🔅 coins
"spent_rpoints": 35.094528, // the number of 🔅coins that were withdrawn from the balance for completing the task
"spent_repost_points": 0, // the number of bonus points for reposts that were deducted for completing the task. For DeepFace Video, the field will always be 0, because payment is made in 🔅 coins
"spent_balance": 0, // the amount of money from the main balance that was withdrawn for completing the task. For DeepFace Video, the field will always be 0, because payment is made in 🔅 coins
"spent_rbalance": 0, // the amount of money from the bonus balance that was withdrawn for completing the task. For DeepFace Video, the field will always be 0, because payment is made in 🔅 coins
"remaining_points": 820, // remaining balance ⭐️points after completing the task
"remaining_rpoints": 3739.2603184, // balance on balance 🔅coins after completing the task
"remaining_repost_points": 0, // the balance of points on the balance of reposts after completing the task
"remaining_balance": 0, // balance on the main balance after completing the task
"remaining_rbalance": 3341.37 // balance in the bonus balance after completing the task
},
"language": "", // variable not used for DeepFace Video
"prompt": "", // variable not used for DeepFace Video
"status": 2, // task status, where 2 is successful completion
"status_description": "completed", // text explanation of the task status, where completed means successful completion
"start_at": 1711501452, // unixtime, task start time
"finish_at": 1711501554, // unixtime, task completion time
"created_at": 1711501412, // unixtime, client submission time
"updated_at": 1711501554 // unixtime, time of last job status update
}
}
}The order of processing completed tasks for replacing a face in a video (DeepFace Video), submitted via the Yes Ai API
Upon successful execution of the face replacement process within a video, you will be granted an exclusive link to retrieve the "MP4" formatted video. This link will remain active on our server for a duration of one hour.
It is imperative that you promptly download the finalized video to your server once the task is concluded.
Restrictions on Task Submission and Status Monitoring
Tasks can be initiated in Yes Ai through the API and their progress can be monitored as per the defined guidelines.
Guidelines for videos and images submitted for new tasks:
Video files must not exceed 50 megabytes in size
Permitted video file format: mp4
Image files containing faces for video insertion must not exceed 5 megabytes in size
Permitted image file formats: jpeg, jpg, png
Issuing POST requests to initiate new tasks through the API:
Limit the initiation of new tasks to a maximum frequency of once every second.
The maximum number of tasks allowed in the Yes Ai queue (this queue is utilized for all job types initiated via the Yes Ai API):
Ensure the queue does not exceed 8 tasks at any time.
Should the creation of tasks in your system occur at a higher frequency, it is recommended to manage an independent queue for your jobs.
Issuing GET requests to check the progress status of tasks previously initiated:
Status inquiries should be limited to a maximum frequency of once every second.
For any inquiries regarding the use of the Yes Ai API, please contact the official technical support through the Telegram messenger at @yes_ai_support.