# General Data Structure and Platform Specifications
# Service Access Point
| Region Name | Public Network Access Address | VPC Access Address |
|---|---|---|
| East China | aigc.softsugar.com |
# Specifications for Capturing Videos for Character Modeling
In order to perfectly clone character images, please adhere to the guidelines for capturing and producing videos of SenseTime Digital Humans. This includes video and audio content, which will be used for training and testing 2D digital human models. For specific details, please refer to: Capture Specifications (opens new window) and Video Material Self-Inspection Form (opens new window)。
# Video Composition Parameter Input Specification
To create a video composition task, correct 'param' information needs to be passed, including various video composition parameters (this parameter is a JSON-escaped string). Please refer toParameter Description and JSON Example 以及Example Results (opens new window) 。
# Live Streaming Parameter Input Specification
To create a live streaming task, correct 'param' information needs to be passed, including various parameters (this parameter should be a JSON-escaped string). Please refer to: Live Streaming Script JSON Definition Explanation and Example以及Live Streaming Takeover JSON Definition Explanation and Example 。
# Web JS Code Partial Example
For the convenience of web clients to better understand the form of API access and usage, here are partial web JS code examples for some functional modules, including: live streaming creation, live streaming takeover, live streaming closure, creation of tasks for generating/updating character models and querying task status, creation of video composition tasks and querying task status, creation of TTS voice model generation tasks and querying task status, etc. Please refer to:Code Example (opens new window)。
# Common Return Parameters
All interfaces return data in the following structured format. Specific business content is returned in the 'data' field.
| Field | Type | Required | Description |
|---|---|---|---|
code | Integer | True | Status code |
message | String | True | Error message |
data | Object | False | Returned data |
# Paging Information
| Field | Type | Required | Description |
|---|---|---|---|
pageNo | Integer | True | Current page number |
numberPages | Integer | True | Total number of pages |
numberRecords | Integer | True | Total number of records |
pageSize | Integer | True | Number of records per page |
startIndex | Integer | True | Starting index of the current page |
# HTTP Callback Event Notification
This document introduces the callback mechanism, usage process, and authentication principle of HTTP callback event notification.
# HTTP Callback Mechanism
You need to deploy an HTTP service to receive callback messages and provide a callback URL. The platform will configure accordingly. When an event occurs, the PAAS server will initiate an HTTP POST request to this URL, and the event notification content will be delivered via the HTTP Body. Your HTTP service performs signature authentication on the HTTP POST request. If the authentication is successful, responding with a status code of 200 is considered a successful callback. If any other status code is responded or if the response times out, it is considered a callback failure. For authentication principles, please refer to HTTP Callback Authentication Principle. After a successful callback, the configured callback URL will receive the corresponding event notification content. If the callback fails, the VOD service will continue to retry the callback 2 times, for a total of up to 3 times. After exceeding 3 times, the callback event notification for this instance will be discarded.
# HTTP Callback Authentication Principle
PAAS service supports adding specific signature headers during HTTP (including HTTPS) callbacks, which are used for signature authentication by the callback message receiving server to prevent illegal or invalid requests.
# Notice
Whether to enable HTTP callback authentication is at your discretion (it is recommended). Once AuthKey (authentication key) is set, all authentication-related content will be carried during the callback, which can be used by the callback message receiving server for authentication. Setting AuthKey will not affect the original functionality. It is up to you to decide whether to verify it. If AuthKey is not set, there will be no impact.
# Authentication Parameters
The specific authentication parameters added to the callback HTTP message body are as follows:
| Field | Type | Required | Description |
|---|---|---|---|
timestamp | Integer | False | UNIX timestamp, positive integer, fixed length of 10 digits, represents the time of callback request initiation since January 1, 1970, in seconds. |
signature | String | False | Signature string, a 32-character lowercase MD5 value. For detailed instructions, please refer to the signature algorithm below. (After calculating the MD5, convert the value to hexadecimal string format. Note: If the number of bits after conversion for each byte is not sufficient, leading zeros should be added.) |
# Signature Algorithm
The calculation of the signature relies on the following fields:
| Field | Example | Description |
|---|---|---|
Callback URL | https://www.example.com/your/callback | The callback URL set by the user. |
timestamp | 1693206851 | UNIX timestamp, positive integer, fixed length of 10 digits, represents the time of callback request initiation since January 1, 1970, in seconds. |
AuthKey | abcde1231693206851 | The authentication key provided by the user, 16-32 characters long, must contain uppercase letters, lowercase letters, and numbers simultaneously. |
Concatenate the above three fields and calculate the MD5 value, i.e.:
MD5Content = callbackURLtimestampAuthKey
signature = md5sum(MD5Content)
The method for calculating the signature field is shown as follows:
signature = md5sum(https://www.example.com/your/callback1693206851abc123) = 863151b586912152aacee3124f81e301
# Callback Message Receiver Server Verification Rules
- The callback message receiver concatenates the callback URL, timestamp, and AuthKey strings set in the callback, calculates the MD5 value, obtains the encrypted string, and then compares the encrypted string with the signature field. If they do not match, the request is considered illegal.
- The callback message receiver server retrieves the current time and subtracts it from the timestamp field time carried in the callback request. If it exceeds the specified time set by the callback message receiver server (such as 5 minutes, defined by the callback message receiver server itself), the request is considered invalid.
# Switching AuthKey
To ensure that the callback functionality is not affected when switching AuthKeys, the callback message receiver server needs to smoothly transition between the old and new AuthKeys, allowing for authentication with both for a period of time. This transition should be managed by the callback message receiver server.
The recommended operation sequence is as follows:
Define a new AuthKey for the user. Upgrade the callback message receiver server to support authentication with both the new and old AuthKeys. Update the AuthKey to the latest one in the on-demand console. After observing for a period, remove the compatibility with the old AuthKey from the callback message receiver server. Transition completed.
# HTTP Callback Usage Instructions
# Prerequisites
- You have deployed an HTTP/HTTPS service to receive callback messages.
# Description of Error Message
| Error Code | Description |
|---|---|
| 0 | Success |
| 400 | Error |
| 500 | Error |
| 10101001 | IAM identity ID invalid. |
| 10999999 | Access center exception. |
| 20999999 | Generation platform exception. |
| 30999999 | Digital asset platform exception. |
| 50101503 | Parsing authorization error. |
| 50101504 | Authorization does not exist. |
| 50102101 | Mobile phone number cannot be empty. |
| 50102102 | Mobile phone number is not valid, must be an 11-digit real mobile phone number. |
| 50102103 | Verification code cannot be empty. |
| 50102104 | Verification code is not valid. |
| 50102105 | Verification code has expired. |
| 50102107 | The account name is invalid, it must be a valid email or phone number |
| 50102106 | The account name cannot be empty |
| 50102108 | The password cannot be empty |
| 50102109 | Incorrect account or password |
| 50102110 | The user name cannot be empty |
| 50102111 | Business information cannot be empty |
| 50102112 | The email cannot be empty |
| 50102113 | The password must consist of a combination of letters, numbers, and symbols, with 6-16 characters, case-sensitive |
| 50102114 | The maximum length of the user name is 25 characters |
| 50102115 | The maximum length of business information is 50 characters |
| 50102116 | The maximum length of the email is 80 characters |
| 50102117 | The passwords do not match |
| 50102118 | Failed to send verification code |
| 50102119 | Email address rules: digits, letters, underscores + @ + digits, English letters + . + English letters (length is 2-4) |
| 50102120 | Error in changing password |
| 50102121 | Failed to create a new account |
| 50102122 | Failed to retrieve account information |
| 50102123 | Invalid type of verification code |
| 50102124 | The email already exists |
| 50102125 | The account id must be greater than 0 |
| 50103201 | The order does not exist |
| 50103202 | To restore an order on the business side, the current status must be Cancelled |
| 50103203 | Not deleted by an administrator on the management side |
| 50103204 | To delete an order, the current status must be Cancelled |
| 50103205 | To cancel an order, the current status must be Urged/Pending/Processing |
| 50103206 | To urge an order, the current status must be Urged/Pending/Processing |
| 50103207 | The above special effects have been removed from the shelves, unable to generate orders, please clear and reorder |
| 50103208 | The number of special effects included in the generated order cannot be 0 |
| 50103209 | Cannot urge repeatedly within 24 hours |
| 50103210 | Only administrators can perform this operation |
| 50103211 | Orders that have been deleted cannot change status |
| 50103212 | Administrators cannot view canceled orders |
| 50103213 | Only administrators can view order details |
| 50103214 | Administrators cannot create orders |
| 50103215 | Invalid order status |
| 50103216 | Invalid order sorting name |
| 50103217 | Only corporate accounts can urge |
| 50103218 | Only corporate accounts can cancel |
| 50104401 | The special effect tag is associated with special effects |
| 50104402 | Duplicate special effect tag names |
| 50105301 | Invalid file key/expiration time |
| 50105302 | File upload failed |
| 50105303 | File download failed |
| 50105304 | File deletion failed |
| 50105305 | Failed to obtain input stream |
| 50105306 | S3 file does not exist |
| 50105307 | Exception in compressing S3 file |
| 50106403 | Exception in decompressing the special effect package |
| 50106404 | Exception in parsing the special effect package |
| 50106405 | Exception in encrypting the special effect package |
| 50106406 | JSON file in the special effect package does not exist |
| 50106407 | Cannot delete because the special effect is in use |
| 50106703 | Invalid sorting name |
| 50107601 | Invalid app_id |
| 50107603 | Invalid signature |
| 50107604 | Illegal data format |
| 50107607 | Data decryption failed |
| 50107605 | Cannot find APP key |
| 50107606 | Cannot find SDK key |
| 60102101 | Mobile number cannot be empty |
| 60102102 | Invalid mobile number, must be a real 11-digit number |
| 60102103 | Verification code cannot be empty |
| 60102108 | Password cannot be empty |
| 60102112 | Email cannot be empty |
| 60102116 | The maximum length of the email is 80 characters |
| 60102119 | Email address rules: digits, letters, underscores + @ + digits, English letters + . + English letters (length is 2-4) |
| 60102123 | Invalid type of verification code |
| 60102124 | The email already exists |
| 60102126 | Account does not exist |
| 60102127 | Please enter an email or mobile number |
| 60102128 | Account pending activation |
| 60102129 | This account has been disabled, please contact the administrator to enable the account |
| 60102130 | Continuous login failed %s times, please try again after %s |
| 60102131 | Exception in generating RSA key pair |
| 60102132 | Failed to generate key pair! |
| 60102133 | Public key cannot be empty |
| 60102134 | Exception in obtaining RSA private key |
| 60102135 | Public key has expired, please regenerate |
| 60102136 | Error occurred in decryption |
| 60102137 | RSA decryption exception |
| 60102138 | Incorrect password |
| 60102139 | Mobile number already exists |
| 60102140 | User status is abnormal |
| 60102141 | Role already exists |
| 60102142 | User-role relationship already exists |
| 60102143 | Role-permission relationship already exists |
| 60102144 | Failed to send email %s |
| 60102145 | The service validity period is unreasonable |
| 60102146 | No permission for the operation related to the given parameter (please verify if the user exists, if there are any conflicts in user parameters, if the status is normal, and if the role relationship data is reasonable, etc.) |
| 60102147 | The number of roles to be created must be greater than 0 |
| 60102148 | The number of roles to be exported must be greater than 0 |
| 60102149 | The start date of the service validity period cannot be empty |
| 60102150 | The end date of the service validity period cannot be empty |
| 60102151 | appId cannot be empty |
| 60102152 | appKey cannot be empty |
| 60102153 | New password cannot be empty |
| 60102154 | No roles bound under this application |
| 60102155 | The number of roles to be created and exported cannot be empty |
| 60102156 | Account not within the valid period |
| 60102157 | appId already exists |
| 60102158 | appId and appKey do not match |
| 60102159 | Please enter a contact name in Chinese or English with 2-8 characters |
| 60111101 | APP does not exist |
| 60111301 | APP does not exist |
| 60112505 | Access authorization expired, please log in again |
| 60112160 | Third-party system signature verification failed |
| 60112161 | Refresh token too frequently, limit interval to %s hours |
| 60112162 | Illegal grant type |
| 70107701 | Tag is in use |
| 70107702 | System tags cannot be modified or deleted |
| 70104703 | Tag name cannot be empty |
| 70104704 | Tag type cannot be empty |
| 80107807 | Current algorithm status prohibits restart |
| 80107811 | Exception in requesting virtual human service |
| 80108801 | OPEN FEIGN request source is illegal |
| 80108802 | No algorithm worker node instances in online status in the registry |
| 80108803 | The algorithm worker node instance is not in online status in the registry |
| 80108804 | No algorithm worker node instances in the registry |
| 80108805 | Negotiation failed with algorithm worker node instance |
| 80108806 | Algorithm scheduling service failed to obtain cartoon style collection from virtual human service interface |
| 80108810 | Algorithm scheduling service failed to obtain cartoon style and its download URL collection from virtual human service interface |
| 80109809 | No available idle task resources for scheduling in the worker node, please try again later |
| 80109814 | Scheduling command does not exist |
| 80109815 | Exception in requesting algorithm service |
| 80109817 | Dispatcher does not support the algorithm of the worker |
| 80109833 | The current algorithm task has an abnormal status in the scheduling center |
| 80117823 | Load value is illegal or empty. |
| 80117824 | No worker is using this GAN algorithm category. |
| 80117825 | This feature is not registered in commercial services. |
| 80117826 | Error in pulling the entire category feature configuration. |
| 80117827 | Function-zip mapping does not exist. |
| 80115947 | The current service resource has reached its limit, unable to create a live stream, please try again later. |
| 80115950 | No historical parameter records, update not supported, need to regenerate the model. |
| 80115962 | Your trial account live streaming has reached the usage limit: %s channels, no resources available, please try again later. |
| 80115963 | Your official account live streaming has reached the usage limit: %s channels, no resources available, please try again later. |
| 80115964 | Live streaming service has reached the limit of available resources, no resources available, please try again later. |
| 80115983 | The number of %s tasks created has reached the concurrent task limit of the current account, please try again later. |
| 81107808 | The algorithm worker node does not support the created thread type. |
| 81114812 | Virtual human cartoon character SDK failed to create avatar. |
| 81114813 | Virtual human cartoon character SDK handler resources exhausted, please try again later. |
| 81114816 | Style not found. |
| 81117819 | Bling SDK failed to create GAN effect handle. |
| 81117820 | Image size cannot exceed 5MB. |
| 81117821 | SDK task is running. |
| 81117822 | Function value is illegal. |
| 81117828 | Property editing function-zip mapping configuration does not exist. |
| 81118829 | AvatarPackage Handler exception. |
| 81118830 | AvatarPackage Handler creation exception, error code. |
| 81118831 | AvatarPackage Handler License verification failed, error code. |
| 81118832 | AvatarPackage Handler Process failed, error code. |
| 81118836 | AvatarPackage FBX does not support compression. |
| 81118837 | AvatarPackage JSON format is abnormal. |
| 81118838 | Material file is missing necessary type files, unable to generate character FBX/GLB files. |
| 81118839 | AvatarPackage Handler is processing, please try again later. |
| 82116818 | Task id cannot be empty. |
| 83119834 | No idle video generation worker available. |
| 83119308 | File decompression exception. |
| 83115905 | Account id cannot be empty. |
| 83115906 | Failed to start 2D digital human algorithm task. |
| 84115913 | Video generation character model format is incorrect, must be in zip format and contain assets and models resources. |
| 84115914 | Video task stylization data input format is illegal, only supports video formats: mp4/csv/vid/ebm/mov, image formats: jpg/JPG/jpeg/JPEG/png/bmp |
| 83115920 | Failed to start 2D digital human live streaming algorithm task. |
| 83115921 | Failed to stop 2D digital human live streaming algorithm task. |
| 83115922 | Failed to initialize 2D digital human live streaming algorithm task. |
| 83115923 | Failed to take over 2D digital human live streaming algorithm task. |
| 83115924 | Live streaming video generation character model format is incorrect, must be in zip format and contain assets and models resources. |
| 83115951 | The file format in the background/foreground URL does not meet the type requirement, 0(jpg,jpeg,png,gif,bmp,tiff,svg), 1(mp4,avi,mov,wmv,flv,mkv) |
| 83115952 | Initialization failed. |
| 83115961 | urtcUid must be a pure number not exceeding 32 digits in uint length. |
| 83115965 | When urtcUseExternalApp is true, urtcToken, urtcAppId, urtcChannelId, urtcUid are required. |
| 83115971 | Failed to reorder the live streaming takeover list. |
| 83115972 | Failed to get the live streaming takeover list. |
| 83115973 | Failed to join the live streaming list. |
| 83115977 | Live streaming takeover is initializing, reordering not supported. |
| 84115912 | Cannot generate character model task after the quantity of generated character models exceeds the total amount. |
| 84115915 | Live streaming initialization not yet completed, please wait. |
| 84115916 | Live streaming has already started, please do not start again. |
| 84115917 | Live streaming task is abnormal, cannot be started. |
| 84115918 | Live streaming task not in progress, cannot be taken over. |
| 84115919 | Live streaming task has been completed or is in abnormal state, no need to close. |
| 84999920 | Please follow these parameter rules: assetScale is optional, default value is 1.0, range is 0.1 to 3; assetStart and assetEnd are optional and must appear in pairs, both cannot be negative, assetEnd must be greater than assetStart; greenParamsSpillByalpha range is 0.3 to 0.7, greenParamsBlurKs must be greater than or equal to 1, and must be an odd number |
| 84115921 | Current live streaming takeover is abnormal. |
| 84115922 | Current live streaming is being taken over, please try again later. |
| 84115923 | Current live streaming has been closed, cannot be started. |
| 84115925 | The current user does not have permission to perform this operation. |
| 84115926 | Current connection has been lost for over 10 minutes, please reconnect. |
| 84115927 | Request parameter is illegal. |
| 84115928 | Resource path is invalid. |
| 84115929 | Task/session does not exist. |
| 84115930 | Live streaming is in progress. |
| 84115931 | Takeover error, unknown reason. |
| 84115932 | Live streaming status can be: 5 (Completed), 9 (Abnormal). |
| 84115933 | Live streaming has started, channel Id is %s. |
| 84115934 | Live streaming has been initialized, channel Id is %s. |
| 84115940 | Failed to create TTS personal voice model generation task. |
| 84115941 | Failed to cancel TTS personal voice model generation task. |
| 84115942 | Failed to get TTS personal voice model task details. |
| 84115935 | Video generation JSON file parsing error. |
| 84115943 | Token is illegal. |
| 84115945 | Live streaming initialization JSON file parsing error. |
| 84115944 | Cannot create new live streaming tasks after using more than the total available live streaming duration. |
| 84115946 | Live streaming has been closed, subsequent operations cannot be performed. |
| 84115948 | The current remaining allocable routes are %s (total - public reserved - already set), please adjust. System resources will be preempted when the current configuration number > total available number! |
| 84115949 | Only tasks that are waiting or in progress can be cancelled. |
| 84115955 | Refreshing rtcToken too frequently, limit interval to %s hours. |
| 84115956 | This live streaming session does not have this channelId. |
| 84115953 | Live streaming has been closed. |
| 84115957 | This account has tasks that are currently live streaming; to avoid causing abnormal effects, changing account tags is temporarily not supported. |
| 84115958 | Cannot generate tts model tasks after the quantity of generated tts models exceeds the total amount. |
| 84115959 | Character model file URL is illegal, or not in zip format. |
| 84115960 | Live streaming push JSON file parsing error. |
| 84115966 | Only tasks that have been cancelled or are abnormal are allowed to be regenerated. |
| 84115967 | Duplicate tasks %s in billing details. |
| 84115968 | Failed to acquire lock %s. |
| 84115969 | Task does not exist or status does not satisfy. |
| 84115970 | Administrators cannot create tasks. |
| 84115974 | Failed to change priority of TTS personal voice model task. |
| 84115975 | Cannot generate 2k character model tasks after the quantity of generated 2k character models exceeds the total amount. |
| 84115976 | Cannot generate 4k character model tasks after the quantity of generated 4k character models exceeds the total amount. |
| 84115979 | The number of created voice cloning tasks has reached the current account's task concurrency limit, please try again later. |
| 84115980 | NLP APP does not exist. |
| 84115981 | NLP Skill does not exist. |
| 84115982 | Task concurrency limit needs to be greater than 0. |
| 84115984 | Found %s pieces of data, the data volume is large, please export and view. |
| 89999998 | Request limit key cannot be empty. |
| 89999999 | Your access is too frequent, please try again later. |
| 90113801 | This user has reached the maximum number of characters created. |
| 90113802 | This user has reached the maximum number of characters exported. |
| 90113803 | Verification of character creation number is abnormal. |
| 90113804 | Exception in obtaining raw materials. |
| 90113805 | Exception in deleting temporary folder. |
| 90113806 | Character generation exception, please check the uploaded image according to the requirements or try again later. |
| 90113807 | No available Handler. |
| 90113808 | Exception in updating JSON file. |
| 90113809 | Algorithm return failure. |
| 90113810 | SDK Aimodel file path does not exist. |
| 90113811 | Please check the correct face image is uploaded before attempting to regenerate. |
| 90113812 | Unsupported image format. |
| 90113813 | File format incorrect leading to load failure. |
| 90113815 | Please check the automatic face configuration model for this character style. |
| 90114814 | Only jpg/png format images are supported. |
| 90114833 | Character does not exist. |
| 90114834 | Update too frequent, please try again later. |
| 90114835 | File content cannot be parsed, please refer to the system-generated character material file. |
| 90115901 | Priority execution of task failed. |
| 90115903 | Failed to start hyper-realistic algorithm task. |
| 90115904 | Failed to stop hyper-realistic algorithm task. |
| 99999990 | Access Forbidden. |
| 99999991 | Service Unavailable. |
| 99999992 | Hystrix Bad Request. |
| 99999993 | Hystrix Runtime Exception. |
| 99999994 | Hystrix Timeout. |
| 99999995 | Feign Error. |
| 99999996 | Invalid Input. |
| 99999997 | Gateway Error. |
| 99999998 | External Service Error. |
| 99999999 | Error. |