> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia de uso de materiais de pessoas reais no Doubao

> Crie materiais de pessoas reais com confirmação pessoal pela página web, use referências asset:// na geração de vídeos Doubao Seedance e consulte, repita solicitações e exclua materiais.

Os materiais de pessoas reais permitem usar em vídeos a imagem de uma pessoa que concluiu pessoalmente a confirmação. O fluxo consiste em criar um grupo de materiais, obter a confirmação da própria pessoa pela página web, adicionar materiais, aguardar sua disponibilidade e enviar uma tarefa de geração de vídeo.

Esta página usa materiais de imagem como exemplo e a API da AIHubMix para gerenciá-los, dando preferência à nova API `/ai/v1/videos` para gerar vídeos. Clientes que já usam `/v1/videos` podem consultar o [exemplo do protocolo compatível](#compatible-video).

<h2 id="prerequisites">
  Pré-requisitos
</h2>

* Tenha uma API Key válida da AIHubMix e leia seu valor pela variável de ambiente `AIHUBMIX_API_KEY`.
* Antes de usar a nova API de vídeo, ative as [tarefas assíncronas](/pt/api/async-tasks) no console e confirme que a conta tem saldo suficiente e permissão para usar o modelo de destino.
* A pessoa retratada deve concordar com os usos previstos e concluir pessoalmente o processo de confirmação na página web. Adicione apenas materiais da mesma pessoa a um grupo.
* Prepare um link direto para a imagem que possa ser lido pelo provedor de modelos e permaneça válido durante o processamento do material.
* Os exemplos de linha de comando exigem Bash, curl e jq. Execute as etapas no mesmo terminal e guarde os IDs retornados do grupo de materiais, da sessão de confirmação, do material e da tarefa de vídeo.

<Note>
  O guia oficial da BytePlus para materiais de pessoas reais abrange Seedance 2.0 e Seedance 2.5. O exemplo principal da nova API de vídeo nesta página usa o ID de modelo da AIHubMix `doubao-seedance-2-5-260628`, validado em produção; a versão específica, os tipos de mídia de referência e os parâmetros dependem do Schema atual do modelo e dos recursos disponíveis para a conta. Consulte o escopo em [Validação deste fluxo](#verified-flow) e não presuma que todas as versões do Seedance aceitam materiais de pessoas reais.
</Note>

Prepare o ambiente do terminal; a API Key já deve ter sido definida pelo seu ambiente de execução:

```bash theme={null}
set -euo pipefail
: "${AIHUBMIX_API_KEY:?请先配置 AIHUBMIX_API_KEY 环境变量}"
BASE_URL="https://aihubmix.com"
MODEL="doubao-seedance-2-5-260628"
```

<h2 id="create-group">
  1. Criar um grupo de materiais
</h2>

```bash theme={null}
GROUP_JSON=$(curl --fail-with-body -sS --max-time 60 \
  -X POST "$BASE_URL/ai/v1/asset-groups" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"我的真人素材"}')
printf '%s\n' "$GROUP_JSON" | jq .
GROUP_ID=$(printf '%s' "$GROUP_JSON" | jq -er '.id')
```

O corpo da requisição aceita apenas `name`, que não pode estar vazio e tem limite de 100 caracteres. A criação bem-sucedida retorna HTTP `201`, com status inicial `pending_auth`.

Os campos públicos do grupo de materiais são `id`, `object`, `name`, `status`, `created_at` e `updated_at`. O valor de `object` é sempre `asset_group`, e os campos de tempo usam segundos Unix. Nas etapas seguintes, `status=active` indica que o grupo já permite adicionar materiais.

Se a resposta de criação for perdida, consulte primeiro a lista para evitar criar outro grupo diretamente:

```bash theme={null}
curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups?limit=20" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .
```

A lista retorna `data`, `has_more` e `next_after`. Para obter a próxima página, envie `after` com o valor de `next_after` da página anterior; `limit` tem valor padrão `20` e máximo `100`. O nome não funciona como identificador de idempotência; use o ID e o horário de criação para identificar o grupo de materiais.

<h2 id="create-verification">
  2. Obter o link de confirmação pessoal
</h2>

Crie uma sessão de confirmação, sem corpo de requisição:

```bash theme={null}
SESSION_JSON=$(curl --fail-with-body -sS --max-time 60 \
  -X POST "$BASE_URL/ai/v1/asset-groups/$GROUP_ID/verification-sessions" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY")
SESSION_ID=$(printf '%s' "$SESSION_JSON" | jq -er '.id')
printf '%s' "$SESSION_JSON" | jq '{id, status, expires_at, verification_url}'
```

A criação bem-sucedida retorna HTTP `201`. Os campos públicos são `id`, `object`, `group_id`, `status`, `created_at`, `expires_at` e `completed_at`; `object` é sempre `verification_session`, os campos de tempo usam segundos Unix e `completed_at` é `null` enquanto a sessão não estiver concluída.

<Warning>
  `verification_url` é retornado apenas na resposta de criação bem-sucedida; as consultas posteriores não retornam o link novamente. Envie-o prontamente à pessoa retratada e não o inclua em logs públicos, repositórios de código ou capturas de tela enviadas ao suporte. A validade é determinada por `expires_at`; após a expiração, o link original não pode mais ser usado.
</Warning>

A própria pessoa deve abrir `verification_url`, conferir a entidade e a finalidade exibidas na página, ler e aceitar os termos aplicáveis e concluir as operações conforme as instruções. O guia oficial da BytePlus informa que esse processo exige login em uma conta pessoal da BytePlus; quando a página solicitar permissão para a câmera, a própria pessoa deve operar o dispositivo e conceder a permissão.

A página oficial pode incluir etapas como o envio de materiais; siga as instruções exibidas. Ainda é necessário executar a próxima etapa de criação de materiais pela API desta página e obter o ID do material retornado pela AIHubMix; não substitua diretamente esse ID por outros IDs de materiais exibidos na página web.

<h2 id="check-verification">
  3. Consultar o resultado da confirmação
</h2>

```bash theme={null}
curl --fail-with-body -sS "$BASE_URL/ai/v1/verification-sessions/$SESSION_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .

curl --fail-with-body -sS "$BASE_URL/ai/v1/asset-groups/$GROUP_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .
```

| Status da sessão | Próxima etapa                                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `creating`       | A sessão ainda está sendo criada; consulte novamente mais tarde e contate o suporte se ela continuar sem conclusão |
| `pending`        | Aguardando a conclusão pela pessoa ou a confirmação do resultado; continue consultando mais tarde                  |
| `verified`       | A confirmação pessoal foi concluída; confira também se o grupo de materiais está `active`                          |
| `rejected`       | Esta tentativa não foi aprovada; verifique as instruções da página e inicie outra tentativa                        |
| `expired`        | Esta tentativa expirou; inicie novamente a confirmação                                                             |
| `failed`         | Esta tentativa falhou; verifique a mensagem de erro e contate o suporte se necessário                              |

O cliente pode consultar a cada 10 a 15 segundos e definir um limite local de espera. Esse intervalo é uma recomendação de uso. Mesmo que a página web indique conclusão ou exiba uma página em branco, confirme pela API que a sessão está `verified` e o grupo está `active` antes de adicionar materiais.

Se uma nova tentativa de criação retornar `409 verification_session_active`, consulte primeiro a sessão existente e o grupo de materiais. Não crie sessões repetidamente quando ainda houver uma sessão válida, o grupo já tiver concluído a confirmação ou o resultado anterior ainda estiver aguardando confirmação. Se a situação persistir, contate o [suporte](/pt/FAQs/Feedback).

<Warning>
  A mensagem `internal error` na página web não indica que a sessão de confirmação terminou. Execute primeiro as duas requisições GET desta seção para consultar a sessão e o grupo; enquanto a sessão estiver `pending`, não crie repetidamente sessões para o mesmo grupo. Adicione materiais somente quando a sessão estiver `verified` e o grupo estiver `active`. O erro da página, por si só, não permite determinar a causa; se a situação persistir, guarde os IDs e contate o suporte.
</Warning>

<h2 id="create-asset">
  4. Criar um material a partir de uma URL de imagem
</h2>

<h3 id="image-requirements">
  Preparação da imagem
</h3>

Forneça uma URL HTTP(S) absoluta que retorne o arquivo de imagem, preferencialmente HTTPS. O link deve permitir leitura sem login nem cabeçalhos adicionais; caminhos locais, endereços de rede interna, Base64 e URLs com nome de usuário e senha não são aceitos pela API de criação de materiais. A URL não deve conter um fragmento `#`.

Segundo o [guia da BytePlus para materiais de pessoas reais](https://docs.byteplus.com/en/docs/ModelArk/2315856), recomenda-se uma foto frontal nítida que atenda aos seguintes requisitos de inclusão na biblioteca de materiais:

| Item                   | Requisito                                                              |
| ---------------------- | ---------------------------------------------------------------------- |
| Formato                | JPEG, PNG, WebP, BMP, TIFF, GIF, HEIC, HEIF                            |
| Tamanho de cada imagem | Menor que 30 MB                                                        |
| Proporção              | Maior que 0.4 e menor que 2.5                                          |
| Largura e altura       | Ambas maiores que 300 pixels e menores que 6000 pixels                 |
| Pessoa                 | A mesma pessoa que concluiu a confirmação para esse grupo de materiais |

Esses são os requisitos oficiais da biblioteca de materiais; o modelo de vídeo pode impor restrições próprias aos materiais de referência. Confira também os requisitos do modelo de destino antes do envio; uma criação HTTP bem-sucedida não significa que o material já passou pelo processamento.

<h3 id="asset-request">
  Requisição de criação
</h3>

Substitua `IMAGE_URL` pelo link direto de uma imagem cujo uso foi autorizado pela pessoa retratada. O domínio do exemplo é apenas um marcador e não fornece uma imagem de pessoa real.

```bash theme={null}
IMAGE_URL="https://cdn.example.com/portrait.jpg"
ASSET_KEY="portrait-image-001"
ASSET_BODY=$(jq -n --arg url "$IMAGE_URL" --arg ref "$ASSET_KEY" \
  '{url: $url, asset_type: "image", client_reference_id: $ref}')
ASSET_JSON=$(curl --fail-with-body -sS --max-time 60 \
  -X POST "$BASE_URL/ai/v1/asset-groups/$GROUP_ID/assets" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ASSET_KEY" \
  -d "$ASSET_BODY")
printf '%s\n' "$ASSET_JSON" | jq .
ASSET_ID=$(printf '%s' "$ASSET_JSON" | jq -er '.id')
```

| Campo da requisição   | Obrigatório | Descrição                                                       |
| --------------------- | ----------- | --------------------------------------------------------------- |
| `url`                 | Sim         | URL acessível do arquivo de material                            |
| `asset_type`          | Sim         | `image`, `video` ou `audio`; este exemplo usa `image`           |
| `client_reference_id` | Não         | Identificador do material na aplicação, com limite de 128 bytes |

O corpo da requisição aceita apenas os três campos acima. `Idempotency-Key` é um cabeçalho opcional, com limite de 128 bytes, sem espaços em branco no início ou no fim nem caracteres de controle. Para os limites de arquivos de áudio e vídeo, consulte o guia oficial acima e confira os tipos e as durações aceitos pelo modelo de destino.

A primeira criação geralmente retorna HTTP `201`; a reutilização de um material existente retorna `200`; quando o resultado ainda aguarda confirmação e o status é `reconciling`, retorna `202`. Sempre leia o `status` do objeto.

Os campos públicos do material são `id`, `object`, `group_id`, `asset_type`, `status`, `client_reference_id`, `created_at`, `updated_at` e `deleted_at`. `object` é sempre `asset`; `client_reference_id` não é retornado quando não foi fornecido ou foi excluído, e `deleted_at` é `null` enquanto o material não tiver sido excluído. Os campos de tempo usam segundos Unix. As consultas não retornam a URL original da imagem; mantenha seus próprios registros na aplicação.

<h2 id="wait-active">
  5. Aguardar a disponibilidade do material
</h2>

```bash theme={null}
curl --fail-with-body -sS "$BASE_URL/ai/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .
```

| Status do material | Significado e ação                                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `creating`         | A criação ainda não foi concluída; guarde o ID e consulte mais tarde                                                           |
| `processing`       | Em processamento; continue consultando                                                                                         |
| `active`           | Pode ser usado como material de referência para vídeo                                                                          |
| `failed`           | O processamento do material falhou; confira a imagem e os requisitos de correspondência da pessoa                              |
| `reconciling`      | O resultado da criação ou exclusão ainda aguarda confirmação; continue consultando e não use o material em vídeos por enquanto |
| `deleting`         | Exclusão em andamento; não use o material em vídeos por enquanto                                                               |
| `deleted`          | Exclusão concluída; não use mais o material em vídeos                                                                          |

Você pode consultar a cada 10 a 15 segundos e definir um limite local de espera. Interromper a consulta periódica local não cancela a operação no servidor.

<Warning>
  Quando o resultado da criação é desconhecido e nenhum resultado correspondente é encontrado por um período prolongado, o material pode permanecer em `reconciling`, o que também pode afetar a exclusão do material ou do grupo. Guarde o ID e os identificadores da requisição original e contate o suporte; não altere os identificadores para criar materiais repetidamente nem presuma que haverá limpeza automática após algum tempo.
</Warning>

<h2 id="generate-video">
  6. Gerar um vídeo usando o material
</h2>

A referência de vídeo usa o `id` completo retornado pela AIHubMix na resposta de criação do material, no formato `asset://<asset_id>`. Todos os materiais referenciados na mesma requisição devem pertencer ao mesmo grupo e à conta atual, e todos devem estar `active`. O grupo de materiais também deve permanecer disponível.

| Tipo de material | `input_references[].type` na nova API | Campo aninhado na API compatível |
| ---------------- | ------------------------------------- | -------------------------------- |
| `image`          | `image_url`                           | `image_url.url`                  |
| `video`          | `video_url`                           | `video_url.url`                  |
| `audio`          | `audio_url`                           | `audio_url.url`                  |

O tipo de referência deve corresponder ao `asset_type` usado na criação do material. `asset://` é usado nos campos de referência de vídeo e não é uma URL para download pelo navegador.

<h3 id="native-video">
  Novo protocolo de vídeo
</h3>

Primeiro, confira o Schema atual do modelo selecionando o caminho do endpoint:

```bash theme={null}
curl --fail-with-body -sS "$BASE_URL/call/schema/models/$MODEL/endpoints" \
  | jq '.endpoints[] | select(.path == "/ai/v1/videos") | .request.schema'
```

Envie a requisição após confirmar que o modelo aceita imagens de referência. O exemplo abaixo usa os parâmetros do Seedance 2.5 validados com sucesso em produção nesta execução: `duration=4`, `resolution="480p"`, `aspect_ratio="3:4"` e `generate_audio=false`. A nova API usa diretamente `input_references[].url`, com `ASSET_ID` definido como o ID do material retornado anteriormente pela AIHubMix:

```bash theme={null}
VIDEO_BODY=$(jq -n --arg model "$MODEL" --arg asset "asset://$ASSET_ID" \
  '{model: $model,
    prompt: "The person in the reference image smiles and waves at the camera.",
    duration: 4,
    resolution: "480p",
    aspect_ratio: "3:4",
    generate_audio: false,
    input_references: [{type: "image_url", url: $asset}]}')
VIDEO_JSON=$(curl --fail-with-body -sS --max-time 120 \
  -X POST "$BASE_URL/ai/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$VIDEO_BODY")
printf '%s\n' "$VIDEO_JSON" | jq .
VIDEO_ID=$(printf '%s' "$VIDEO_JSON" | jq -er '.id')
export VIDEO_ID
```

A nova API usa um inteiro `duration` para indicar a duração solicitada; os demais valores permitidos dependem do Schema do modelo. `resolution="480p"` é a faixa de resolução solicitada e não garante largura ou altura fixa de 480 pixels na saída; as dimensões reais são as do arquivo gerado. Para os quadros inicial e final, use `frame_images[].image_url.url` e defina também `frame_type`, somente quando o modelo aceitar esse recurso. Consulte todos os parâmetros em [Geração de vídeos](/pt/api/aihubmix-video-generation).

<h3 id="compatible-video">
  Protocolo de vídeo compatível
</h3>

Para clientes existentes que usam `/v1/videos`, coloque a referência em `content` ou `extra_body.content`, com a URL aninhada no objeto de mídia correspondente. Este exemplo usa `extra_body.content`:

<Note>
  O exemplo compatível mantém `doubao-seedance-2-0-260128` e foi elaborado com base no contrato existente da API compatível e nas instruções oficiais da BytePlus sobre referências a materiais. A geração de vídeos com Seedance 2.0 e a criação compatível por `/v1/videos` não foram testadas nesta execução; os resultados da validação do Seedance 2.5 na nova API não podem ser aplicados diretamente a este exemplo.
</Note>

```bash theme={null}
COMPAT_MODEL="doubao-seedance-2-0-260128"
COMPAT_BODY=$(jq -n --arg model "$COMPAT_MODEL" --arg asset "asset://$ASSET_ID" \
  '{model: $model,
    prompt: "The person in the reference image smiles and waves at the camera.",
    extra_body: {content: [{type: "image_url", image_url: {url: $asset}, role: "reference_image"}]}}')
curl --fail-with-body -sS --max-time 120 \
  -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$COMPAT_BODY" | jq .
```

Escolha apenas um dos dois exemplos para executar; cada criação de vídeo é uma requisição independente. Não inclua `input_references` na requisição compatível. Se `content` for fornecido nos dois locais, `extra_body.content` substitui o `content` de nível superior; recomenda-se fornecê-lo em apenas um local.

Use o `id` retornado pela API compatível em `GET /v1/videos/{id}` para consultar e, após a conclusão, em `GET /v1/videos/{id}/content` para baixar. Não consulte IDs da API compatível em `/ai/v1/videos`. Veja os detalhes na [API de vídeo compatível](/pt/api/Video-Gen).

<h2 id="poll-download">
  7. Consultar periodicamente e baixar o vídeo da nova API
</h2>

O exemplo Python abaixo dá continuidade apenas à etapa anterior de criação pela nova API, lê `VIDEO_ID` das variáveis de ambiente e não cria outra tarefa. É necessário instalar `requests`.

```python theme={null}
import os
import time
from pathlib import Path

import requests

base_url = "https://aihubmix.com"
video_id = os.environ["VIDEO_ID"]
headers = {"Authorization": f"Bearer {os.environ['AIHUBMIX_API_KEY']}"}
deadline = time.monotonic() + 1800

while time.monotonic() < deadline:
    response = requests.get(
        f"{base_url}/ai/v1/videos/{video_id}", headers=headers, timeout=30
    )
    response.raise_for_status()
    task = response.json()
    status = task["status"]
    if status == "completed":
        break
    if status in {"failed", "cancelled"}:
        raise RuntimeError(f"视频任务未完成：{task.get('error') or status}")
    time.sleep(15)
else:
    raise TimeoutError(f"本地等待已结束，请稍后继续查询原任务：{video_id}")

temporary = Path("result.mp4.part")
with requests.get(
    f"{base_url}/ai/v1/videos/{video_id}/content",
    headers=headers,
    timeout=120,
    stream=True,
) as response:
    response.raise_for_status()
    with temporary.open("wb") as output:
        for chunk in response.iter_content(chunk_size=1024 * 1024):
            if chunk:
                output.write(chunk)
temporary.replace("result.mp4")
print("视频已保存为 result.mp4")
```

Os 30 minutos são o limite local de espera do exemplo e não representam um tempo limite da tarefa no servidor. HTTP `200` em uma consulta não significa geração bem-sucedida; é necessário verificar `status`. As consultas periódicas usam `/ai/v1/videos/{id}`; a API unificada de tarefas `/ai/v1/tasks/{id}` fornece um retrato somente leitura.

Use a mesma API Key da criação da tarefa para consultar e baixar o vídeo. Baixe e armazene o resultado assim que estiver concluído; os resultados têm prazo de retenção definido por `expires_at` e, após a expiração, podem retornar `410 artifact_expired`.

<h3 id="verified-flow">
  Validação deste fluxo
</h3>

A validação em produção de 2026-09-07 usou um link direto HTTPS público para um JPEG, a confirmação concluída pela própria pessoa na página web e os parâmetros do Seedance 2.5 acima, com os seguintes resultados observados:

| Etapa                                | Resultado desta execução                                                                                            |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Criar grupo de materiais             | HTTP `201`, `status=pending_auth`                                                                                   |
| Criar sessão de confirmação          | HTTP `201`, `status=pending`                                                                                        |
| Consultar após a confirmação pessoal | Sessão com HTTP `200` e `status=verified`; grupo de materiais `active`                                              |
| Criar e consultar material de imagem | Criação com HTTP `201` e `status=processing`; consulta posterior com HTTP `200` e `status=active`                   |
| Criar e consultar vídeo na nova API  | Criação com HTTP `200` e `status=in_progress`; consulta posterior com HTTP `200`, `status=completed` e `error=null` |
| Baixar vídeo                         | HTTP `200`, `Content-Type: video/mp4`; arquivo totalmente decodificado com ffmpeg                                   |

O arquivo desta execução tinha 1,558,358 bytes; o ffprobe identificou H.264, 24 fps, 560 × 752 pixels, 4.041667 segundos e nenhuma faixa de áudio. Esses valores correspondem a esta geração e não significam que todas as requisições produzirão as mesmas dimensões, duração ou tamanho de arquivo.

Na primeira abertura da página de confirmação, foi exibido `internal error`; a consulta posterior pela API ainda retornava `pending`, e a causa do erro da página não foi confirmada. Depois, o teste usou uma nova página de um grupo de teste independente e, após a própria pessoa concluir as operações, a sessão foi confirmada como `verified` e o grupo como `active`. O novo grupo foi apenas a abordagem adotada neste teste, sem constituir uma recomendação geral para recriar grupos repetidamente nem indicar que a sessão original terminou.

A geração de vídeos com Seedance 2.0, a criação pela API compatível, os materiais de áudio e vídeo, os quadros inicial e final, a exclusão e outras combinações de exceções não foram testados nesta execução. As respectivas descrições mantêm como base o contrato das APIs e a documentação oficial; esta validação não abrange todos os cenários do guia.

<h2 id="idempotency">
  Novas tentativas idempotentes
</h2>

* Se a criação de um material exceder o tempo limite ou a resposta for perdida, mantenha o `Idempotency-Key`, o `client_reference_id`, a URL e o `asset_type` originais e reenvie a mesma requisição. Se qualquer um dos dois identificadores corresponder a um material existente da mesma conta e do mesmo grupo, esse material será reutilizado.
* Se a URL ou o `asset_type` associado ao mesmo identificador mudar, será retornado `409 asset_idempotency_conflict`. A atualização de uma URL de imagem assinada também conta como alteração de URL.
* Sem nenhum dos identificadores, não há garantia de deduplicação entre requisições. Use um novo identificador somente quando tiver confirmado que deseja criar outro material.
* Após obter o ID do material, priorize a consulta por `GET /ai/v1/assets/{id}`. `reconciling` não equivale a falha; não crie outro material com novos identificadores.
* Após a conclusão da exclusão do material, os identificadores de idempotência originais deixam de ser mantidos. Não dependa deles para recuperar materiais excluídos nem reenvie requisições antigas de criação.
* As regras de idempotência desta seção se aplicam apenas à criação de materiais. Elas não se aplicam à criação de grupos de materiais, sessões de confirmação ou vídeos. Se a resposta de criação de vídeo na nova API for perdida, procure primeiro a tarefa original com `GET /ai/v1/videos?limit=20&order=desc` para evitar geração duplicada.

<h2 id="delete-assets">
  Excluir materiais e grupos de materiais
</h2>

Antes de excluir, confirme que todos os vídeos que referenciam o material foram finalizados, incluindo as tarefas enviadas pela API compatível. A exclusão não pode ser desfeita; os arquivos de vídeo já baixados devem ser gerenciados por você.

Excluir um material individual:

```bash theme={null}
curl --fail-with-body -sS -X DELETE "$BASE_URL/ai/v1/assets/$ASSET_ID" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .
```

O retorno `202` indica que a exclusão ainda está em andamento. Continue consultando por `GET /ai/v1/assets/{id}` até `status=deleted`. Repetir a exclusão retorna o status atual; se for `reconciling`, continue verificando o resultado e contate o suporte se a situação persistir.

A exclusão de todo o grupo também exclui os materiais contidos nele e exige o envio explícito de `cascade=true`:

```bash theme={null}
curl --fail-with-body -sS -X DELETE \
  "$BASE_URL/ai/v1/asset-groups/$GROUP_ID?cascade=true" \
  -H "Authorization: Bearer $AIHUBMIX_API_KEY" | jq .
```

Após a aceitação, a resposta é `202`; consulte por `GET /ai/v1/asset-groups/{id}`. `deleting` indica processamento, `partially_deleted` indica que a exclusão ainda não está completa e somente `deleted` indica conclusão. Por padrão, a lista não exibe grupos de materiais excluídos.

`409 asset_group_in_use` indica que ainda existem operações ou tarefas de vídeo não finalizadas. Aguarde, consulte os status relacionados e tente novamente. Confirme por conta própria que as tarefas de vídeo compatíveis foram finalizadas; não dependa da requisição de exclusão para detectar automaticamente o uso por todas as tarefas compatíveis.

<h2 id="faq">
  Perguntas frequentes
</h2>

<h3 id="verification-pending">
  Por que ainda não consigo adicionar materiais após concluir as operações na página web?
</h3>

Consulte primeiro a sessão de confirmação e o grupo de materiais, usando `verified` e `active` como referência. Faça a mesma verificação se a página exibir `internal error`; enquanto o status for `pending`, não crie repetidamente sessões para o mesmo grupo. Se o resultado ainda não estiver confirmado, consulte novamente mais tarde; se a situação persistir, forneça os IDs ao suporte, sem enviar o link de confirmação nem fotos da pessoa.

<h3 id="video-failed">
  Por que a geração de vídeo ainda falha quando o material está disponível?
</h3>

Verifique se a referência usa o ID do material retornado pela AIHubMix, se todos os materiais pertencem ao mesmo grupo, se os tipos de mídia correspondem e se o modelo atual aceita as respectivas entradas. O status `active` indica disponibilidade do material; ainda é necessário verificar separadamente o status de conclusão e as mensagens de erro da tarefa de vídeo.

<h3 id="errors">
  Como tratar os erros comuns da API?
</h3>

| HTTP | `error.code`                                                                 | Ação                                                                                 |
| ---- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| 400  | `invalid_request`                                                            | Confira os campos, a estrutura da requisição e o protocolo de vídeo usado            |
| 400  | `asset_group_invalid`                                                        | Confira o nome do grupo de materiais                                                 |
| 400  | `asset_invalid`                                                              | Confira a URL, o tipo de material e os identificadores da requisição                 |
| 400  | `asset_binding_mismatch`                                                     | Referencie apenas materiais do mesmo grupo em uma requisição de vídeo                |
| 400  | `cascade_confirmation_required`                                              | Após confirmar a intenção de excluir todo o grupo, envie `cascade=true`              |
| 401  | `authentication_failed`                                                      | Confira a variável de ambiente da API Key e o cabeçalho de autenticação              |
| 403  | `async_not_enabled`                                                          | Ative as tarefas assíncronas antes de usar a nova API de vídeo                       |
| 404  | `asset_group_not_found`, `asset_not_found`, `verification_session_not_found` | Confira o ID do recurso e a conta à qual ele pertence                                |
| 409  | `asset_group_not_verified`                                                   | Consulte o resultado da confirmação pessoal e aguarde a disponibilidade do grupo     |
| 409  | `verification_session_active`                                                | Consulte a sessão ou o grupo existente para evitar novas tentativas duplicadas       |
| 409  | `asset_not_ready`                                                            | Consulte o status do material e aguarde `active` antes de gerar o vídeo              |
| 409  | `asset_idempotency_conflict`                                                 | Confira a URL e o tipo originais associados ao identificador                         |
| 409  | `asset_group_in_use`                                                         | Aguarde a finalização das operações e tarefas de vídeo relacionadas antes de excluir |
| 503  | `asset_group_unavailable`, `verification_unavailable`, `asset_unavailable`   | Tente novamente mais tarde; se a indisponibilidade persistir, contate o suporte      |

Para outros erros de vídeo, consulte os [códigos de erro de tarefas assíncronas](/pt/api/async-tasks#error-codes). Ao enviar um relato, forneça o horário da ocorrência, o status HTTP, `error.code`, o `error.tid` retornado (se houver) e os IDs dos recursos relacionados; não envie a API Key, o link de confirmação nem URLs de imagens assinadas.

<h2 id="references">
  Referências
</h2>

* [BytePlus: adicionar materiais de pessoas reais](https://docs.byteplus.com/en/docs/ModelArk/2315856)
* [BytePlus: gerar vídeos de retrato com Seedance](https://docs.byteplus.com/en/docs/ModelArk/2608626)
* [Geração nativa de vídeos da AIHubMix](/pt/api/aihubmix-video-generation)
* [API de vídeo compatível com OpenAI](/pt/api/Video-Gen)
* [Tarefas assíncronas](/pt/api/async-tasks)

Última atualização: 2026-09-07