Listar ativos

Disponibilidade

Esta página documenta a rota de gerenciamento de ativos do Modelflare. As chamadas exigem uma chave de API inteligente válida ou uma chave de API de grupo de mídia, um canal de mídia disponível e a permissão necessária.

Nota

O gateway registra IDs de ativos do provedor, status e propriedade do usuário. A biblioteca local Castaly permanece separada do namespace do ativo do provedor.

Ponto final

POST https://modelflare.dev/volc/asset/ListAssets

Autenticação

Use uma chave de API Modelflare:

bash

-H "Authorization: Bearer YOUR_MODELFLARE_API_KEY"

Envie Idempotency-Key com solicitações de criação, atualização e exclusão. Tentar novamente a mesma chave para o mesmo usuário reproduz a resposta salva sem repetir a mutação.

Solicitação

Listar ativos com filtros opcionais de nome, grupo e tipo de grupo. Aguarde Status: Active antes de usar um ID em uma solicitação Seedance.

Campo	Tipo	Obrigatório	Descrição	Exemplo
model	string	Sim	Modelo de cobrança. O padrão é volc-asset.	volc-asset
Filter.Name	string	Não	Filtro difuso de nome de ativo.	character
Filter.GroupIds	string[]	Não	Filtrar por IDs de grupo.	["group-20260320141746-zsf6b"]
Filter.GroupType	AIGC	LivenessFace	Não	Filtrar por tipo de grupo.
PageNumber	integer	Não	Número da página. O padrão é 1.	1
PageSize	integer	Não	Itens por página. O padrão é 10.	10

Exemplo JSON:

JSON

{
  "model": "volc-asset",
  "Filter": {
    "Name": "character",
    "GroupIds": [
      "group-20260320141746-zsf6b"
    ],
    "GroupType": "AIGC"
  },
  "PageNumber": 1,
  "PageSize": 10
}

exemplo de cURL:

bash

curl --request POST https://modelflare.dev/volc/asset/ListAssets \
  --header "Authorization: Bearer YOUR_MODELFLARE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "volc-asset",
  "Filter": {
    "Name": "character",
    "GroupIds": [
      "group-20260320141746-zsf6b"
    ],
    "GroupType": "AIGC"
  },
  "PageNumber": 1,
  "PageSize": 10
}'

Resposta

A solicitação foi bem-sucedida.

Campo	Tipo	Obrigatório	Descrição	Exemplo
Items[]	object[]	Não	Objetos de ativos com identidade, tipo, grupo, status, projeto e carimbos de data/hora.	{ Id, Name, AssetType, GroupId, Status, ... }
Items[].Id / Name	string	Não	Identidade do ativo e nome de exibição.	asset-20260528140922-d9646 / character-reference
Items[].AssetType / GroupId	string	Não	Tipo de ativo e grupo proprietário.	Image / group-20260320141746-zsf6b
Items[].Status / ProjectName	string	Não	Estado de processamento e nome do projeto.	Active / default
Items[].CreateTime / UpdateTime	string	Não	Carimbos de data e hora de criação e atualização da ISO 8601.	2026-03-20T14:25:01Z
Items[].URL	string	Não	URL do arquivo temporário. A vida útil documentada é de 12 horas; use asset://<ID> para solicitações de geração.	https://example.com/temporary-asset
Items[].Error	object	Não	Erro de processamento com Code e Message quando Status é Failed.	{ Code, Message }
PageNumber	integer	Não	Número da página retornada.	1
PageSize	integer	Não	Tamanho da página retornado.	10
TotalCount	integer	Não	Total de ativos correspondentes.	2

Exemplo de resposta:

JSON

{
  "Items": [
    {
      "Id": "asset-20260528140922-d9646",
      "Name": "character-reference",
      "AssetType": "Image",
      "GroupId": "group-20260320141746-zsf6b",
      "Status": "Active",
      "ProjectName": "default"
    }
  ],
  "PageNumber": 1,
  "PageSize": 10,
  "TotalCount": 1
}

Erros

Estado	Significado
400	A solicitação é inválida.
401	A chave API está faltando ou não foi autorizada.

Exemplo de corpo de erro (quando retornado):

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed."
  }
}

A criação de imagem, vídeo e áudio é assíncrona. Após receber um ID de ativo, chame GetAsset e utilize a referência asset://<ID> somente quando o status for Active.