Saltar para o conteúdo principal

Início Rápido

A geração 3D é uma operação assíncrona, e todo o fluxo é dividido em três etapas:
Exemplo mais simples

Visão Geral das Interfaces

Base URL: https://aihubmix.com Método de autenticação: Bearer Token
Diferentemente da interface de vídeo, a interface 3D não possui o endpoint de download /content nem o endpoint de exclusão DELETE: os arquivos gerados são baixados diretamente pelo content_url presente em output[] da resposta de consulta.

Modelos Suportados

Tipos de geração (generate_type)

Detalhes da API

Cabeçalhos da requisição

Criar tarefa de geração 3D

Corpo da requisição

Regras de validação dos parâmetros
  • prompt e input_references são mutuamente exclusivos (envie apenas um deles); somente generate_type: "Sketch" permite enviar os dois simultaneamente (esboço + descrição em texto).
  • Em cada item de input_references, deve ser enviado exatamente um entre image_url e image_base64:
    • image_url aceita apenas URLs públicas http(s), sem suporte a data URL (use image_base64 em vez disso);
    • image_base64 não pode exceder 6MB após a decodificação.
  • O hy-3d-3.1 não suporta o tipo de geração LowPoly.
  • O tamanho total do corpo da requisição não pode exceder 10MB.
Uso de extra_body: os parâmetros nativos do upstream (como polygon_type) podem ser colocados no nível superior de extra_body para repasse. Os parâmetros a seguir devem ser enviados como campos de nível superior — se aparecerem em extra_body, será retornado 400: model, prompt, image_url, image_base64, generate_type, enable_pbr, face_count, result_format; multi_view_images (imagens de múltiplas vistas) ainda não é suportado.

Exemplo de resposta

Descrição dos valores de status

Consultar status da tarefa

Consulte esta interface para verificar se a tarefa foi concluída. Recomenda-se consultar a cada 10~15 segundos. A consulta não é cobrada.

Exemplo de resposta (geração concluída)

Campos de output[]
content_url e preview_url são links temporários e expiram após algum tempo; baixe e transfira para o seu próprio armazenamento assim que a tarefa for concluída. O ID da tarefa pode ser consultado por 24 horas a partir da criação (o campo expires_at indica o momento limite de consulta); após a expiração, a consulta retornará erro. Os links temporários aceitam apenas requisições GET; requisições HEAD retornam 403.

Exemplos de Uso

Exemplos Completos de Chamada

Cobrança

  • Cobrança por execução: o preço é determinado pela combinação de modelo × generate_type × ativação de PBR × definição de número de faces × definição de formato; veja os preços na Galeria de Modelos.
  • A cobrança ocorre no momento da criação bem-sucedida da tarefa; consultar o status da tarefa e baixar os arquivos gerados não são tarifados.
  • Combinações de parâmetros sem preço configurado retornam 400 diretamente na criação, sem gerar cobrança.

FAQ

Quanto tempo leva a geração 3D?

Normalmente leva alguns minutos, dependendo do modelo, do tipo de geração e da configuração do número de faces. Recomenda-se consultar a interface de consulta em intervalos de 10~15 segundos.
  • O ID da tarefa pode ser consultado por 24 horas a partir da criação; o campo expires_at na resposta indica o momento limite de consulta.
  • content_url / preview_url são links temporários do upstream e expiram após algum tempo; baixe e salve o quanto antes após a conclusão da tarefa.

Posso enviar prompt e imagem de referência ao mesmo tempo?

Não, os dois são mutuamente exclusivos — a única exceção é generate_type: "Sketch" (esboço para 3D), que permite enviar simultaneamente a imagem do esboço e a descrição em texto.

Qual é a diferença entre os tipos de generate_type?

O que fazer quando a tarefa falha?

Quando o status for failed, o campo error na resposta conterá a informação do erro:
As causas comuns de falha incluem: violação de conteúdo, formato de imagem não suportado, imagem de referência inacessível, entre outros. Ajuste de acordo com a informação do erro e tente novamente.
Última atualização: 2026-07-17