Biblioteca privada de retratos virtuales

package
main
import
(
"fmt"
"github.com/bytedance/sonic"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/credentials"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/session"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/universal"
)
func
main
()
{
config := byteplus.NewConfig().WithCredentials(credentials.NewStaticCredentials(
"<your_ak>"
,
"<your_sk>"
,
""
)).WithRegion(
"ap-southeast-1"
)
sess, _ := session.NewSession(config)
resp, err := universal.New(sess).DoCall(
universal.RequestUniversal{
ServiceName:
"ark"
,
Action:
"CreateAssetGroup"
,
Version:
"2024-01-01"
,
HttpMethod:  universal.POST,
ContentType: universal.ApplicationJSON,
},
&
map
[
string
]any{
"Name"
:
"<GROUP_NAME>"
,
"Description"
:
"<GROUP_DESC>"
,
"ProjectName"
:
"default"
,
},
)
if
err !=
nil
{
fmt.Printf(
"error: %v\n"
, err)
return
}
if
resp ==
nil
{
return
}
respData, err := sonic.Marshal(resp)
fmt.Println(
string
(respData))
}

{
"Id"
:
"group-20260318033332-*****"
}
Upload an asset
Use the
POST
CreateAsset API to upload an asset.
Tip
The CreateAsset API is asynchronous. Processing may be queued, which can increase ingestion time. Upload-time SLAs are
not guaranteed
.
Provide the following in the request:
GroupId
: Required. Asset group ID.
URL
: Required. Accessible image URL.
AssetType
: Required. Support uploading image/video/audio assets. You need to specify the asset type here:
Image/Video/Audio
. For specific restrictions on asset files, see the
Assets API documentation
.
Name
: Optional. Asset name, which can be used for asset management, such as the asset file name.
Tip
Different models support different input audio and video durations. We recommend recording the duration of uploaded audio and video files before upload, so end users can identify which assets can be used with Dreamina Seedance 2.0 and Seedance 2.5 models.
Tip
This field is used only for fuzzy search when calling the ListAssets API and is not included in model inference. For details on generating videos with assets, see
Use preset digital characters
and
3. How should I reference uploaded assets in the prompt (content.text)?
Moderation
: Optional. Specifies whether to turn off the Content Pre-filter review for the current asset.
By default, the Content Pre-filter review is on.
To skip most non-baseline content security review policies, set this parameter to
"Moderation": { "Strategy": "Skip"}
ProjectName
: Optional. Specifies the resource project name. Defaults to
default
. Resources in a project can only be used by inference endpoints within that project. For more information about project, see the related
IAM docs
.
Tip
If
ProjectName
is not specified in the request, the asset will be uploaded to the
default
project by default. You need to use this field to ensure the asset is uploaded to the corresponding project.
Notes
:
Each request uploads a single asset file.
This request returns the asset ID. You can use the GetAsset API to view whether the upload was successful.

package
main
import
(
"fmt"
"github.com/bytedance/sonic"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/credentials"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/session"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/universal"
)
func
main
()
{
config := byteplus.NewConfig().WithCredentials(credentials.NewStaticCredentials(
"<YOUR_AK>"
,
"<YOUR_SK>"
,
""
)).WithRegion(
"ap-southeast-1"
)
sess, _ := session.NewSession(config)
resp, err := universal.New(sess).DoCall(
universal.RequestUniversal{
ServiceName:
"ark"
,
Action:
"CreateAsset"
,
Version:
"2024-01-01"
,
HttpMethod:  universal.POST,
ContentType: universal.ApplicationJSON,
},
&
map
[
string
]any{
"GroupId"
:
"group-20260324142802-f7wmx"
,
"URL"
:
"<IMAGE_URL>"
,
"AssetType"
:
"Image"
,
"Moderation"
:
map
[
string
]any{
// Skip the Content Pre-filter review, must turn off content pre-filter on the console first
"Strategy"
:
"Skip"
,
},
"ProjectName"
:
"default"
,
},
)
if
err !=
nil
{
fmt.Printf(
"error: %v\n"
, err)
return
}
if
resp ==
nil
{
return
}
respData, err := sonic.Marshal(resp)
fmt.Println(
string
(respData))
}

{
"Id"
:
"asset-20260318071009-*****"
}
Retrieve virtual portraits (API & Console)
You can retrieve virtual portrait assets using the following methods.

package
main
import
(
"fmt"
"github.com/bytedance/sonic"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/credentials"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/session"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/universal"
)
func
main
()
{
config := byteplus.NewConfig().WithCredentials(credentials.NewStaticCredentials(
"<YOUR_AK>"
,
"<YOUR_SK>"
,
""
)).WithRegion(
"ap-southeast-1"
)
sess, _ := session.NewSession(config)
resp, err := universal.New(sess).DoCall(
universal.RequestUniversal{
ServiceName:
"ark"
,
Action:
"GetAsset"
,
Version:
"2024-01-01"
,
HttpMethod:  universal.POST,
ContentType: universal.ApplicationJSON,
},
&
map
[
string
]any{
"Id"
:
"asset-20260324143042-*****"
,
"ProjectName"
:
"default"
,
// Make sure to specify the correct project name where the asset is stored
},
)
if
err !=
nil
{
fmt.Printf(
"error: %v\n"
, err)
return
}
if
resp ==
nil
{
return
}
respData, err := sonic.Marshal(resp)
fmt.Println(
string
(respData))
}

{
"GroupId"
:
"group-20260318033332-7vw4m"
,
"Status"
:
"Active"
,
"Moderation"
:
{
"Strategy"
:
"Default"
},
"CreateTime"
:
"2026-03-18T03:57:10Z"
,
"AssetType"
:
"Image"
,
"UpdateTime"
:
"2026-03-18T03:57:14Z"
,
"LastInferenceTime"
:
"2026-07-24T10:08:49+08:00"
,
"ProjectName"
:
"default"
,
"Id"
:
"asset-20260318035710-*****"
,
"Name"
:
""
,
"URL"
:
"https://ark-media-asset-ap-southeast-1.tos-ap-southeast-1.volces.com/300060****/03301616086559****.jpg?X-Tos-Algorithm=***********"
}
Tip
LastInferenceTime
indicates the most recent time when an asset was used to submit a video generation task. The value is based on the time when the task was submitted. For details, see the
GetAsset API reference
.
Query asset information
You can use
POST
ListAssets to query assets.
Supports:
Querying by group ID (GroupId), asset statuses (Statuses), and asset name (Name). Filter assets that meet all criteria.
Fuzzy search using Name and precise search using GroupId, making it easier to retrieve required assets.
Sorting results using SortBy and SortOrder.
Tip
ListAssets
supports NextToken pagination and page-number pagination. For pagination methods, parameter usage, and restrictions, see the
ListAssets API reference
.

package
main
import
(
"fmt"
"github.com/bytedance/sonic"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/credentials"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/session"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/universal"
)
func
main
()
{
config := byteplus.NewConfig().WithCredentials(credentials.NewStaticCredentials(
"<your_ak>"
,
"<your_sk>"
,
""
)).WithRegion(
"ap-southeast-1"
)
sess, _ := session.NewSession(config)
resp, err := universal.New(sess).DoCall(
universal.RequestUniversal{
ServiceName:
"ark"
,
Action:
"ListAssets"
,
Version:
"2024-01-01"
,
HttpMethod:  universal.POST,
ContentType: universal.ApplicationJSON,
},
&
map
[
string
]any{
"Filter"
:
map
[
string
]any{
"GroupIds"
:  []
string
{
"group-20260324142802-*****"
},
"GroupType"
:
"AIGC"
,
"Statuses"
:  []
string
{
"Active"
,
"Processing"
},
// Supported statuses: Active (Upload successfully, Asset ID available for use), Processing, Failed
},
"MaxResults"
:
2
,
"SortBy"
:
"CreateTime"
,
"SortOrder"
:
"Desc"
,
},
)
if
err !=
nil
{
fmt.Printf(
"list assets error: %v\n"
, err)
return
}
if
resp ==
nil
{
return
}
respData, err := sonic.Marshal(resp)
fmt.Println(
string
(respData))
}

{
"Items"
:
[
{
"Id"
:
"asset-20260318035710-kctzf"
,
"Name"
:
""
,
"AssetType"
:
"Image"
,
"CreateTime"
:
"2026-03-18T03:57:10Z"
,
"UpdateTime"
:
"2026-03-18T03:57:14Z"
,
"LastInferenceTime"
:
"2026-07-24T10:08:49+08:00"
,
"ProjectName"
:
"default"
,
"URL"
:
"https://ark-media-asset-ap-southeast-1.tos-ap-southeast-1.volces.com/300060****/03301616086559****.jpg?X-Tos-Algorithm=***********"
,
"GroupId"
:
"group-20260318033332-*****"
,
"Status"
:
"Active"
,
"Moderation"
:
{
"Strategy"
:
"Default"
}
},
{
"GroupId"
:
"group-20260318033332-*****"
,
"Status"
:
"Active"
,
"Id"
:
"asset-20260318034804-wtnjr"
,
"Name"
:
""
,
"URL"
:
"image_url"
,
"AssetType"
:
"Image"
,
"CreateTime"
:
"2026-03-18T03:48:04Z"
,
"UpdateTime"
:
"2026-03-18T03:48:08Z"
,
"LastInferenceTime"
:
"2026-07-24T02:08:49Z"
,
"ProjectName"
:
"default"
,
"Moderation"
:
{
"Strategy"
:
"Default"
}
}
],
"NextToken"
:
"****bmNyeXB0ZWRfY3Vyc29yIjoiLi4****"
}
Query asset groups
Use
POST
ListAssetGroups to query asset group information.
Supports fuzzy search for asset group names (Name) or provides multiple asset groups (GroupId).
If there are multiple asset groups, the Name field can be used for fuzzy search.
Tip
ListAssetGroups
supports NextToken pagination and page-number pagination. For pagination methods, parameter usage, and restrictions, see the
ListAssetGroups API reference
.

package
main
import
(
"fmt"
"github.com/bytedance/sonic"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/credentials"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/session"
"github.com/byteplus-sdk/byteplus-go-sdk-v2/byteplus/universal"
)
func
main
()
{
config := byteplus.NewConfig().WithCredentials(credentials.NewStaticCredentials(
"<YOUR_AK>"
,
"<YOUR_SK>"
,
""
)).WithRegion(
"ap-southeast-1"
)
sess, _ := session.NewSession(config)
resp, err := universal.New(sess).DoCall(
universal.RequestUniversal{
ServiceName:
"ark"
,
Action:
"ListAssetGroups"
,
Version:
"2024-01-01"
,
HttpMethod:  universal.POST,
ContentType: universal.ApplicationJSON,
},
&
map
[
string
]any{
"Filter"
:
map
[
string
]any{
"Name"
:
"<FIGURE_GROUP>"
,
// Support fuzzy search
"GroupIds"
:  []
string
{
"group-20260324142802-*****"
,
"group-20260324142910-*****"
},
"GroupType"
:
"AIGC"
,
},
"MaxResults"
:
1
,
"SortBy"
:
"CreateTime"
,
"SortOrder"
:
"Desc"
,
},
)
if
err !=
nil
{
fmt.Printf(
"error: %v\n"
, err)
return
}
if
resp ==
nil
{
return
}
respData, err := sonic.Marshal(resp)
fmt.Println(
string
(respData))
}
Return example:

{
"Items"
:
[
{
"UpdateTime"
:
"2026-03-18T03:33:32Z"
,
"Id"
:
"group-20260318033332-*****"
,
"Name"
:
"figure_group_1"
,
"Description"
:
"Figure group 1"
,
"GroupType"
:
"AIGC"
,
"ProjectName"
:
"default"
,
"CreateTime"
:
"2026-03-18T03:33:32Z"
}
],
"NextToken"
:
"****bmNyeXB0ZWRfY3Vyc29yIjoiLi4****"
}
Update/delete assets or asset group
You can call
UpdateAsset
,
UpdateAssetGroup
,
DeleteAsset
, and
DeleteAssetGroup
to update or delete assets and asset groups. For details, see
Virtual portrait library API reference
.
We recommend periodically checking
LastInferenceTime
by using
GetAsset
or
ListAssets
, and proactively deleting assets that you have confirmed are no longer used by using
DeleteAsset
. If an entire asset group is no longer needed, you can call
DeleteAssetGroup
. If
LastInferenceTime
is not returned, it only means that the asset has no invocation record after 2026-07-24. Do not use this field alone to determine that the asset has never been used. Before deletion, confirm against your own business records. Deletion cannot be undone.
Example: Upload assets and use GetAsset to retrieve asset information
The following example creates an asset, queries the asset Status, and determines whether to continue querying or return the corresponding result based on the status.
The code executes the following logic:
createAsset: Upload resources and obtain AssetId
waitForAssetActive: Start querying and repeatedly call getAssetStatus to check the current asset status
Determine based on Status
Processing → Continue polling
Active → Return URL (end). Once the status is
Active
, the Asset ID (in URI format) can be used for video generation.
Failed → Return error (end)
Return the result and print the output
BP_Upload_Asset_Get_Info.go
The query result is illustrated as follows:
text
asset status: Active
asset is active, URL =
asset is active, URL = https://ark-media-asset-ap-southeast-1.tos-ap-southeast-1.volces.com/300060****/03301616086559****.jpg?X-Tos-Algorithm=***********
Sample code in other programming languages
bp-demo.zip
Tip
Caution: Replace the AK and SK in the Demo. To call other interfaces such as ListAssets, replace ACTION and the corresponding request parameters.
Generate video using portrait assets
After obtaining the Asset ID, private portrait assets can be used to generate video.
For details, see
Use preset digital characters
.
Use the asset URI in the
content._url.url
field of the Video Generation API to generate video.
Tip
Asset URI pattern: asset://
<Asset_Id>
Tip
In the prompt you send to the model, reference assets using
type + index
, such as
Image 1
and
Video 1
. The index is the asset's position in the request body.
Do not
use an Asset ID directly in the prompt.
Example: "The girl in
Image 1
is wearing the outfit from
Image 2
and is arranging items on the counter. The boy in
Image 3
is a customer who walks up and asks the girl for her contact information."
For a complete call example, see
3. How should I reference uploaded assets in the prompt (content.text)?
Sample code:

import
os
import
time
# Install SDK:  pip install arkruntime
from
arkruntime
import
Ark
client = Ark(
# The base URL for model invocation
base_url=
"https://ark.ap-southeast.bytepluses.com/api/v3"
,
# Get API Key: https://ai.byteplus.com/ark/region:ap-southeast-1/apikey
api_key=os.environ.get(
"ARK_API_KEY"
),
)
if
__name__ ==
"__main__"
:
print
(
"----- create request -----"
)
create_result = client.content_generation.tasks.create(
model=
"dreamina-seedance-2-0-260128"
,
# Replace with Model ID
content=[
{
"type"
:
"text"
,
"text"
:
"Vertical HD close-up video of a beauty blogger (Image 1). She has bold, glamorous makeup with no facial shine or glare and a sweet smile. She holds a face cream jar (Image 2), presents it directly to the camera. The background is fresh and minimalist. Energetic and sweet style. English voiceover: 'I found my holy grail face cream! It has a cloud-like creamy texture that absorbs instantly. Perfect for post-all-nighter rescue, deep hydration and moisturization—my skin glows naturally even without makeup!' "
},
{
"type"
:
"image_url"
,
"image_url"
: {
"url"
:
"asset://asset-20260225023032-gnzwk"
},
"role"
:
"reference_image"
},
{
"type"
:
"image_url"
,
"image_url"
: {
"url"
:
"https://ark-doc.tos-ap-southeast-1.bytepluses.com/doc_image/r2v_ref_image.png"
},
"role"
:
"reference_image"
},
],
generate_audio=
True
,
ratio=
"16:9"
,
duration=
11
,
watermark=
True
,
)
print
(create_result)
print
(
"----- polling task status -----"
)
task_id = create_result.
id
while
True
:
get_result = client.content_generation.tasks.get(task_id=task_id)
status = get_result.status
if
status ==
"succeeded"
:
print
(
"----- task succeeded -----"
)
print
(get_result)
break
elif
status ==
"failed"
:
print
(
"----- task failed -----"
)
print
(
f"Error:
{get_result.error}
"
)
break
else
:
print
(
f"Current status:
{status}
, Retrying after 30 seconds..."
)
time.sleep(
30
)
FAQs
1. Why is it not possible to generate video or retrieve asset information after assets are uploaded successfully?
The asset library is isolated by
Project (ProjectName)
.
When generating video, inference must be performed using the inference endpoint in the
project where the asset resides
.
If the asset upload is successful but retrieving the asset via the API fails, it may be because different
ProjectName
values were provided when calling the upload asset (CreateAsset) and retrieve asset APIs.
The default value for
ProjectName
is default. If this field is not specified, resources are created in the default project by default.
It is recommended to manage assets within the same project.
For more information about project, see the related
IAM docs
.
Tip
If
ProjectName
is not specified in the request, the asset group will be created in the
default
project by default.
2. How to manage user permissions for the asset library?
You can use
Access control
(IAM) to finely manage user actions in the asset library. Settings can be configured as follows:
Create a custom policy
Open
Access control
>
Create policy
Input the policy name.
Switch to the
JSON editor
, paste the custom policy below into the editor, and click
submit
to save.

curl --location
https://ark.ap-southeast-1.bytepluses.com/api/v3/contents/generations/tasks
\
-X POST \
-H
Content-Type: application/json
\
-H
Authorization: Bearer $ARK_API_KEY
\
-d
{
"model": "seedance-2-0-260128",
"content": [
{
"type": "text",
"text": "Create a fresh, creamy-painting–style short drama with a light, upbeat guitar track driving quick beat cuts. Use a cream-white base with peach-pink highlights, soft lighting, no visual effects—emotion conveyed through expressions. 0–2s: Two fast cuts: the CEO from 【Image 1】 accidentally bumps into the female lead wearing the outfit from 【Image 2】 (character from 【Image 3】); they freeze and lock eyes, then a hand close-up as the CEO pulls off his suit jacket and drapes it over her shoulders. Gentle guitar starts; soft SFX of a coffee cup dropping and fabric brushing. 2–6s: Three fast cuts: the female lead, wrapped in his jacket, looks down and smiles shyly (cheeks flushed, close-up); the CEO watches her back with a faint smile and says “我们一起走吧,” voice style referenced from 【Audio 1】 (profile shot); the two share a black umbrella in the rain, fingertips touch then quickly pull back (near shot). Rainy backdrop references 【Image 4】; each cut hits a light drum accent with rain and umbrella SFX, a subtle soft-mist look. 6–8s: Slow-motion eye-contact smiles; the text portion from 【Image 5】 appears at the lower right, with small text “NEW EP DAILY” at the lower left. Minimal pale-pink petals drift; the guitar resolves gently as the frame freezes on their side-by-side profiles."
},
{
"type": "image_url",
"role": "reference_image",
"image_url": {
"url": "asset://asset-20260224213248-ghm5g"
}
},
{
"type": "image_url",
"role": "reference_image",
"image_url": {
"url": "asset://asset-20260224213248-4lb57"
}
},
{
"type": "image_url",
"role": "reference_image",
"image_url": {
"url": "asset://asset-20260224213248-rc7b7"
}
},
{
"type": "image_url",
"role": "reference_image",
"image_url": {
"url": "asset://asset-20260224213248-wpgsn"
}
},
{
"type": "image_url",
"role": "reference_image",
"image_url": {
"url": "asset://asset-20260224213248-9wrmp"
}
},
{
"type": "audio_url",
"role": "reference_audio",
"audio_url": {
"url": "asset://asset-20260224213248-g5nv7"
}
}
],
"generate_audio": true,
"ratio": "16:9",
"duration": 11,
"watermark": false
}
Last updated:
September 24, 2026 09:33:48
Was this page helpful to you?
Yes
Yes
No
No

{
"Statement"
:
[
{
"Effect"
:
"Allow"
,
"Action"
:
[
"ark:*Asset*"
],
"Resource"
:
[
"*"
]
}
]
}
Grant permissions to users/user groups
Click
User management
>
User
/
User group
, select the user or user group to grant permissions to, and click
Authorize.
In
Policy
, select the policy created in
Step 1
.
(Optional) In
Limit to project resources
, select the project to which the policy applies.
Click
submit.
After completing the above actions, the user or user group can manage assets in the corresponding project.
For more information about IAM, please refer to the
IAM docs
.
3. How should I reference uploaded assets in the prompt (
content.text
)?
In the prompt, reference assets using the format
“asset type + index”
, for example:
Image 1
,
Video 1
,
Audio 1
. The index is the position of that asset within the same asset type in the request body.
Note
: Do not reference assets by
Asset ID
in the prompt.
For example, the sample below includes
five
reference images and
one
reference audio file. Use the prompt format in the example to reference these assets.
Reference
: