tencent cloud

APIs

DocumentationAPIsVideo on DemandAI Creation APIsCreateAigcAdvancedCustomElement

CreateAigcAdvancedCustomElement

Download
Focus Mode
Font Size
Last updated: 2026-09-22 21:50:34

1. API Description

Domain name for API request: vod.intl.tencentcloudapi.com.

This API is used to create an advanced custom AIGC subject.

A maximum of 20 requests can be initiated per second for this API.

We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common Params. The value used for this API: CreateAigcAdvancedCustomElement.
Version Yes String Common Params. The value used for this API: 2018-07-17.
Region No String Common Params. This parameter is not required.
SubAppId No Integer

Video-on-demand (VOD) application ID. For customers who activate VOD services on or after December 25, 2023, this field must be set to the app ID when accessing resources in VOD applications, whether in the default application or a newly created application.
ElementName No String

Subject name, cannot exceed 20 characters.
ElementDescription No String

Subject description, up to 100 characters.
ReferenceType No String

Subject reference method. The availability of subjects customized via video and via images differs.

Enumeration values:

  • video_refer: Video character subject. At this point, refer to element_video_list to define the subject appearance.
  • image_refer: Multi-image subject. At this point, refer to element_image_list to define the subject appearance.
ElementVoiceId No String

Entity timbre, bindable to existing timbres in the timbre library.

  • If the current parameter is empty, the current entity is not bound to a timbre.
  • Only entities customized for video support binding timbres.
ElementVideoList No String

Entity reference video, used to set the entity and its details via video.

  • videos with audio can be uploaded. If the video contains voice, it triggers timbre customization (customize + add to timbre library + bind with entity).
  • The current parameter is required when referencing a video, and invalid when referencing an image.
  • Carried in key:value format, as follows:
    {  "refer_videos":[    {      "video_url":"video_url_1"    }  ]}
    ● video format supports only MP4/MOV
    ● Only 1080p videos with duration between 3s and 8s and an aspect ratio of 16:9 or 9:16 are supported
    ● Up to 1 video can be uploaded, with a video size no more than 200MB
    ● The video_url parameter value cannot be empty
ElementImageList No String

Subject reference image. You can set the subject and its details through multiple images.

  • Including a front reference image and other angle or close-up reference images, where:
    • At least 1 front reference image is required, defined by the frontal_image parameter.
    • 1–3 other reference images are required. They must have differences from the front reference image and are defined by the image_url parameter.
  • Carried in key:value format as follows:
    {  "frontal_image":"image_url_0",  "refer_images":[    {      "image_url":"image_url_1"    },    {      "image_url":"image_url_2"    },    {      "image_url":"image_url_3"    }  ]}
TagList No String

Configure tags for a principal. A principal can be configured with multiple tags.

  • Use key:value to carry them. Details are given below:

[  {        "tag_id": "o_101"  }, {        "tag_id": "o_102"    }]
DisableModeration No String

If the overseas custom subject library is enabled, you can pass in True to use it.

Enumeration values:

  • True: Use the overseas custom subject library.
  • False: Do not use the overseas custom subject library.
SessionId No String

Identifier for deduplication. If a request with the same identifier has been sent within the past three days, an error is returned for the current request. The maximum length is 50 characters. If this is not specified or left empty, deduplication is not performed.
SessionContext No String

Source context. This is used to pass user request information. The task complete callback returns the value of this field. The maximum length is 1000 characters.
TasksPriority No Integer

Task priority. The higher the value, the higher the priority. The value range is from -10 to 10. If this is not specified, the default value is 0.

3. Output Parameters

Parameter Name Type Description
TaskId String

Task ID.
RequestId String The unique request ID, generated by the server, will be returned for every request (if the request fails to reach the server for other reasons, the request will not obtain a RequestId). RequestId is required for locating a problem.

4. Example

Example1 Creating a Multi-Image Subject

Input Example

POST / HTTP/1.1
Host: vod.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: CreateAigcAdvancedCustomElement
<Common request parameters>

{
    "SubAppId": 221073,
    "ElementName": "testname",
    "ElementDescription": "testdescription",
    "ReferenceType": "image_refer",
    "ElementVoiceId": "123333",
    "ElementImageList": "{\"frontal_image\":\"image_url_0\",\"refer_images\":[{\"image_url\":\"image_url_1\"},{\"image_url\":\"image_url_2\"},{\"image_url\":\"image_url_3\"}]}",
    "TagList": "[{\"tag_id\": \"o_101\"}, {\"tag_id\": \"o_102\"}]"
}

Output Example

{
    "Response": {
        "TaskId": "221073-CreateAigcAdvancedCustomElement-927af0f45e354127835f6ec67c48f2a9t",
        "RequestId": "2ff6980c-db91-488b-bb5b-04e8eb5661d2"
    }
}

5. Developer Resources

SDK

TencentCloud API 3.0 integrates SDKs that support various programming languages to make it easier for you to call APIs.

Command Line Interface

6. Error Code

The following only lists the error codes related to the API business logic. For other error codes, see Common Error Codes.

Error Code Description
FailedOperation Operation failed.
FailedOperation.InvalidVodUser VOD service is not enabled.
InternalError Internal error.
InvalidParameter Parameter error.
InvalidParameterValue.SessionContextTooLong SessionContext is too long.
InvalidParameterValue.SessionId Duplicate recognition code. Request deduplicated.
InvalidParameterValue.SessionIdTooLong SessionId is too long.
InvalidParameterValue.SubAppId Parameter value error: app ID.
UnauthorizedOperation Unauthorized operation.
Previous Topic: CreateAigcHunyuan3DTaskNext Topic: CreateAigcAudioClone

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback

Search
    Enter keywords to search documentation