YouQi AI Docs

English

简体中文

English

简体中文

Ark Seedance: Asset Library ​

Gateway proxy for Ark private asset OpenAPI. Sign with platform AK/SK (Volcengine-compatible HMAC). Bearer is rejected. There is no “project group” layer — only local project → asset group → asset. Asset calls are not billed. See Volcengine signing.

Related: Create video task · Task status

Endpoint ​

POST /openapi/volcengine/?Action=<Action>&Version=2024-01-01

Auth ​

HMAC-SHA256 with AccessKeyId / SecretAccessKey from Portal「素材访问密钥」. Do not use ordinary or video API keys.

Conventions ​

ItemNotes
ProjectNameRequired — local project name (not the upstream Ark project). Responses rewrite the local name
model / ModelForbidden; the channel comes from the project’s group binding
IsolationList/Get filtered by local project for this user
NamesGroup / asset Name: Chinese, letters, digits, _, - (max 64 runes). ProjectName stays ASCII
UploadPublic URL only — Ark’s servers GET it with no cookies. Private TOS / expired signed URLs fail with InvalidParameter.DownloadFailed (TOS 403). Smoke-test: https://placehold.co/64x64.png
StatusActive / Processing / Failed / PendingRebuild

Success shape:

json
{
  "ResponseMetadata": {
    "RequestId": "2026062415283493B3836D523A0F3F0AFB",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": { }
}

Supported Actions ​

ActionPurpose
CreateAssetGroup / GetAssetGroup / ListAssetGroups / UpdateAssetGroup / DeleteAssetGroupGroups
CreateAsset / GetAsset / ListAssets / UpdateAsset / DeleteAssetAssets

Out of scope ​

VisualValidate* returns 501.

Asset groups ​

CreateAssetGroup ​

POST /openapi/volcengine/?Action=CreateAssetGroup&Version=2024-01-01

Request parameters ​

NameTypeRequiredDescription
NamestringyesLogical group name, 1–64 chars (Chinese allowed); unique per user and ProjectName
DescriptionstringnoDescription, up to ~256 chars
GroupTypestringnoDefault / currently only AIGC
ProjectNamestringyesLocal project name

Response parameters ​

NameTypeDescription
Result.IdstringNew group ID (e.g. group-…)
Result.NamestringYour logical name (restored by platform)

Request example ​

bash
curl "https://ai.youqi.tech/openapi/volcengine/?Action=CreateAssetGroup&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Name":"figures","Description":"character refs","GroupType":"AIGC","ProjectName":"my_project"}'

Response example ​

json
{
  "ResponseMetadata": {
    "RequestId": "…",
    "Action": "CreateAssetGroup",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "group-20260624152835-lb6rn",
    "Name": "figures"
  }
}

GetAssetGroup ​

POST /openapi/volcengine/?Action=GetAssetGroup&Version=2024-01-01

Request parameters ​

NameTypeRequiredDescription
IdstringconditionalGroup ID; provide Id or Name
NamestringconditionalLogical name; provide Id or Name
ProjectNamestringyesLocal project name

Response parameters ​

NameTypeDescription
Result.IdstringGroup ID
Result.NamestringLogical name
Result.DescriptionstringDescription
Result.GroupTypestringType
Result.ProjectNamestringUpstream project (platform-injected)
Result.CreateTimestringCreated at (UTC, ISO 8601)
Result.UpdateTimestringUpdated at (UTC)

Request example ​

bash
curl "https://ai.youqi.tech/openapi/volcengine/?Action=GetAssetGroup&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Id":"group-20260624152835-lb6rn","ProjectName":"my_project"}'

ListAssetGroups ​

POST /openapi/volcengine/?Action=ListAssetGroups&Version=2024-01-01

Visibility is scoped to your bindings; do not rely on cross-account GroupIds.

Request parameters ​

NameTypeRequiredDescription
PageNumberintegernoPage, default 1
PageSizeintegernoPage size, default 10, max ~100
Filter.NamestringnoFilter by name
Filter.GroupTypestringnoe.g. AIGC
Filter.GroupIdsstring[]noGroup IDs (intersected/rewritten with your visible set)
ProjectNamestringyesLocal project name

Nested fields: Filter.Name means {"Filter":{"Name":"…"}}.

Response parameters ​

NameTypeDescription
Result.TotalCountintegerTotal hits
Result.PageNumberintegerCurrent page
Result.PageSizeintegerPage size
Result.Items[]arrayGroups
Result.Items[].IdstringGroup ID
Result.Items[].NamestringLogical name
Result.Items[].DescriptionstringDescription
Result.Items[].GroupTypestringType
Result.Items[].ProjectNamestringProject
Result.Items[].CreateTime / UpdateTimestringUTC times

Request example ​

bash
curl "https://ai.youqi.tech/openapi/volcengine/?Action=ListAssetGroups&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"PageNumber":1,"PageSize":10,"Filter":{"GroupType":"AIGC"},"ProjectName":"my_project"}'

UpdateAssetGroup ​

POST /openapi/volcengine/?Action=UpdateAssetGroup&Version=2024-01-01

GroupType cannot change after create.

Request parameters ​

NameTypeRequiredDescription
IdstringyesGroup ID
NamestringnoNew logical name, 1–64 chars
DescriptionstringnoNew description
ProjectNamestringyesLocal project name

Response parameters ​

NameTypeDescription
Result.IdstringGroup ID
Result.NamestringUpdated logical name (if renamed)

Request example ​

bash
curl "https://ai.youqi.tech/openapi/volcengine/?Action=UpdateAssetGroup&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Id":"group-20260624152835-lb6rn","Name":"figures_v2","Description":"updated","ProjectName":"my_project"}'

DeleteAssetGroup ​

POST /openapi/volcengine/?Action=DeleteAssetGroup&Version=2024-01-01

Prefer clearing assets with ListAssets first.

Request parameters ​

NameTypeRequiredDescription
IdstringconditionalGroup ID; or Name
NamestringconditionalLogical name; or Id
ProjectNamestringyesLocal project name

Response parameters ​

NameTypeDescription
Result.IdstringDeleted group ID

Request example ​

bash
curl "https://ai.youqi.tech/openapi/volcengine/?Action=DeleteAssetGroup&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Id":"group-20260624152835-lb6rn","ProjectName":"my_project"}'

Assets ​

CreateAsset ​

POST /openapi/volcengine/?Action=CreateAsset&Version=2024-01-01

Async: success means accepted. Poll GetAsset until Status=Active before using asset://<Id> in video tasks.

Request parameters ​

NameTypeRequiredDescription
GroupIdstringyesGroup ID you own
URLstringyesArk downloads this URL anonymously. Private TOS / expired signatures → InvalidParameter.DownloadFailed. Example: https://placehold.co/64x64.png
AssetTypestringyesImage / Video / Audio
NamestringnoDisplay name, 1–64 chars (Chinese allowed); list search only
ProjectNamestringyesLocal project name

Response parameters ​

NameTypeDescription
Result.IdstringNew asset ID (e.g. asset-…)

Request example ​

bash
curl "https://ai.youqi.tech/openapi/volcengine/?Action=CreateAsset&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId":"group-20260624152835-lb6rn",
    "URL":"https://placehold.co/64x64.png",
    "AssetType":"Image",
    "Name":"hero",
    "ProjectName":"my_project"
  }'

Response example ​

json
{
  "ResponseMetadata": {
    "RequestId": "…",
    "Action": "CreateAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260624152850-mftbb"
  }
}

GetAsset ​

POST /openapi/volcengine/?Action=GetAsset&Version=2024-01-01

Use to poll ingest / moderation status after create.

Request parameters ​

NameTypeRequiredDescription
IdstringyesAsset ID
ProjectNamestringyesLocal project name

Response parameters ​

NameTypeDescription
Result.IdstringAsset ID
Result.NamestringName
Result.URLstringTemporary download URL when Active (~12h); often empty while Processing
Result.AssetTypestringImage / Video / Audio
Result.GroupIdstringGroup ID
Result.StatusstringProcessing / Active / Failed
Result.ModerationobjectModeration info
Result.Moderation.Strategystringe.g. Default
Result.CreateTime / UpdateTimestringUTC times
Result.ProjectNamestringProject

Request example ​

bash
curl "https://ai.youqi.tech/openapi/volcengine/?Action=GetAsset&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Id":"asset-20260624152850-mftbb","ProjectName":"my_project"}'

Response example (Active) ​

json
{
  "ResponseMetadata": {
    "RequestId": "…",
    "Action": "GetAsset",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "Id": "asset-20260624152850-mftbb",
    "Name": "hero",
    "URL": "https://….tos-cn-beijing.volces.com/…/product.png?X-Tos-Algorithm=…",
    "AssetType": "Image",
    "GroupId": "group-20260624152835-lb6rn",
    "Status": "Active",
    "Moderation": { "Strategy": "Default" },
    "CreateTime": "2026-06-24T07:28:50Z",
    "UpdateTime": "2026-06-24T07:28:52Z",
    "ProjectName": "default"
  }
}

Poll after ~3s; images often become Active in seconds; video/audio take longer. On Failed / DownloadFailed, open the source URL in a private window — if that 403s, Ark cannot fetch it either.

ListAssets ​

POST /openapi/volcengine/?Action=ListAssets&Version=2024-01-01

Filtered to your asset bindings.

Request parameters ​

NameTypeRequiredDescription
Filter.GroupIdsstring[]noFilter by group (intersected with your groups)
Filter.Statusesstring[]noProcessing / Active / Failed
Filter.NamestringnoFuzzy name match
Filter.AssetTypestringnoImage / Video / Audio
Filter.GroupTypestringnoe.g. AIGC
PageNumberintegernoDefault 1
PageSizeintegernoDefault 10, max ~100
SortBystringnoe.g. CreateTime, GroupId
SortOrderstringnoAsc / Desc
ProjectNamestringyesLocal project name

Response parameters ​

NameTypeDescription
Result.TotalCountintegerTotal hits
Result.PageNumber / PageSizeintegerPagination
Result.Items[]arrayAssets (same fields as GetAsset Result)

Request example ​

bash
curl "https://ai.youqi.tech/openapi/volcengine/?Action=ListAssets&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "Filter": {
      "GroupIds": ["group-20260624152835-lb6rn"],
      "Statuses": ["Active", "Processing"],
      "Name": "figure"
    },
    "PageNumber": 1,
    "PageSize": 10,
    "SortBy": "CreateTime",
    "SortOrder": "Desc",
    "ProjectName": "my_project"
  }'

UpdateAsset ​

POST /openapi/volcengine/?Action=UpdateAsset&Version=2024-01-01

Rename only; URL / AssetType / GroupId are immutable — delete and recreate to replace media.

Request parameters ​

NameTypeRequiredDescription
IdstringyesAsset ID
NamestringnoNew name, 1–64 chars
ProjectNamestringyesLocal project name

Response parameters ​

NameTypeDescription
Result.IdstringAsset ID

Request example ​

bash
curl "https://ai.youqi.tech/openapi/volcengine/?Action=UpdateAsset&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Id":"asset-20260624152850-mftbb","Name":"hero-v2","ProjectName":"my_project"}'

DeleteAsset ​

POST /openapi/volcengine/?Action=DeleteAsset&Version=2024-01-01

Hard delete. Do not delete assets still referenced by in-flight video tasks.

Request parameters ​

NameTypeRequiredDescription
IdstringyesAsset ID
ProjectNamestringyesLocal project name

Response parameters ​

NameTypeDescription
ResultobjectOften {} or { "Id": "…" } (upstream-dependent)

Request example ​

bash
curl "https://ai.youqi.tech/openapi/volcengine/?Action=DeleteAsset&Version=2024-01-01" \
  -H "Content-Type: application/json" \
  -d '{"Id":"asset-20260624152850-mftbb","ProjectName":"my_project"}'

Status and video reference ​

CreateAsset → Processing → Active (referenceable)
                    ↘ Failed (delete only)
StatusMeaningAllowed
ProcessingFetch / moderationPoll GetAsset, may DeleteAsset
ActiveReadyFull ops; asset://<Id> in video tasks
FailedModeration fail or unreachable URLPrefer DeleteAsset

After ingest, reference in create video task content, e.g.:

json
{
  "type": "image_url",
  "role": "reference_image",
  "image_url": { "url": "asset://asset-20260624152850-mftbb" }
}

Must belong to the local project (ProjectName) and be Active.