Como Usar a API Image to 3D Model: Um Guia Completo 2026

A API Imagem para Modelo 3D transforma uma única foto num modelo 3D pronto para produção em segundos — sem necessidade de modelação manual. Modelar manualmente cada ativo é lento e dispendioso, e para estúdios de jogos, aplicações de RA e equipas de comércio eletrónico torna-se rapidamente o gargalo que atrasa os lançamentos. A API imagem para modelo 3D da Meshy remove esse atrito: envie uma imagem, converta-a num modelo 3D em segundos e descarregue uma malha totalmente texturizada em formatos como GLB, FBX e OBJ. Este guia percorre todo o fluxo de trabalho — desde a criação da sua chave de API até à descarga do seu primeiro modelo — com código copiável que pode executar em minutos.

O que é a API Imagem para Modelo 3D?

No seu núcleo, a API Imagem para Modelo 3D é um endpoint REST alimentado pela IA de imagem para modelo 3D da Meshy. Envia uma única imagem (JPG, JPEG ou PNG) como um URL público ou string base64, e a API devolve um modelo 3D texturizado — geometria e texturas de cor base incluídas — em formatos padrão como GLB, FBX, OBJ, USDZ, STL e 3MF. Complementos opcionais incluem mapas PBR, texturas até 4K e miniaturas de pré-visualização de vários ângulos.

Alimentada pelo nosso mais recente modelo Meshy 6, a API permite-lhe configurar a topologia e a contagem de polígonos, definir modos de pose e orientar a texturização com um prompt de texto ou imagem de referência — ideal para gerar ativos para jogos, AR/VR, impressão 3D e visualização de produtos.

O que precisa para usar a API Imagem para 3D?

Não precisa de muito para seguir este guia. Certifique-se de que tem:

• Uma conta Meshy — registe-se gratuitamente se não tiver uma. Irá gerar a sua chave de API a partir do painel de controlo no Passo 1.

• Uma chave de API — usada para autenticar cada pedido. Vamos explicar como criar uma, e pode usar a chave de modo de teste gratuita para acompanhar sem gastar créditos.

• Uma imagem de entrada — um ficheiro .jpg, .jpeg ou .png claro alojado num URL publicamente acessível (ou codificado como base64). Um fundo limpo e um assunto claramente visível dão os melhores resultados.

• Uma forma de fazer pedidos HTTP — curl (usado nos exemplos abaixo), Postman ou qualquer biblioteca HTTP na sua linguagem preferida. Familiaridade básica com APIs REST e JSON é útil mas não obrigatória.

É só isto — não é necessária experiência em modelação 3D. Vamos começar.

Como Converter uma Imagem num Modelo 3D com a API (Guia Passo a Passo)

Passo 1: Configurar as Definições da Sua API

Tudo o que precisa para começar a construir está na página de definições da API. Este é o seu centro de controlo para a API Meshy, e tem três secções principais:

• Chaves de API — gere as chaves que autenticam os seus pedidos.

• Webhooks — seja notificado automaticamente quando as suas tarefas terminam.

• Utilização — acompanhe o seu saldo de créditos restante e o consumo da API em tempo real.

Vamos percorrer cada uma.

Obter a Sua Chave de API

Antes de fazer qualquer pedido, precisa de uma chave de API para autenticar de forma segura. Na página de definições da API, clique em Gerar Chave de API. Cada chave segue o formato msy-<string-aleatória>.

Dica: Depois de gerada, guarde a sua chave de API num local seguro (ex.: gestor de palavras-passe ou variável de ambiente). Trate-a como uma palavra-passe — nunca a submeta para controlo de versões ou a exponha em código do lado do cliente.

Chave de API de Modo de Teste

Durante o desenvolvimento e teste, pode usar a chave de API de modo de teste para explorar a API sem consumir os seus créditos:

msy_dummy_api_key_for_test_mode_12345678

Esta chave especial tem as seguintes características:

• Pode ser usada para fazer pedidos a todos os endpoints da API Meshy.

• Nenhum crédito é consumido ao usar esta chave.

• Todos os pedidos válidos devolvem o mesmo resultado de tarefa de amostra, independentemente dos parâmetros de entrada.

• A estrutura dos dados de resposta corresponde exatamente à da API de produção.

Isto torna-a perfeita para testar a sua integração antes de mudar para a sua chave de API real.

Configurar Webhooks (Opcional)

Gerar um modelo 3D leva tempo, por isso, em vez de consultar repetidamente a API para verificar se uma tarefa está concluída, pode deixar a Meshy notificá-lo no momento em que termina. É para isso que servem os webhooks.

Na secção Webhooks da página de definições, adicione um URL de endpoint onde a Meshy deve enviar notificações de eventos. Quando uma tarefa muda de estado (por exemplo, quando é concluída ou falha), a Meshy envia um pedido HTTP POST para o seu URL com os detalhes da tarefa no payload.

Dica: Os webhooks são a abordagem recomendada para produção. Reduzem chamadas de API desnecessárias e permitem que a sua aplicação reaja aos resultados em tempo real. Para testes rápidos, a consulta periódica também funciona bem. Para testar código de webhook localmente, aponte-o para um URL de proxy de um serviço como smee.io.

Experimente Sem Código — API Playground (Opcional)

Já tem a sua Chave de API? Antes de escrever qualquer código, pode executar uma tarefa real de Imagem para 3D diretamente no seu navegador.

Abra meshy.ai/api-playground, selecione Image to 3D no painel esquerdo e preencha três coisas:

1. Authorization — cole a sua Chave de API (msy-xxxxxxxxxx)

2. Image — carregue um ficheiro .jpg, .jpeg ou .png do seu computador

3. Carregue em Send

O Playground submete a tarefa e consulta os resultados automaticamente. Quando terminar, verá a pré-visualização do modelo 3D e as ligações de descarga diretamente no navegador — sem necessidade de código.

Dica profissional: O painel de pedido/resposta bruto à direita mostra exatamente o que a API envia e devolve. Pode copiar o conteúdo diretamente — obtenha o task_id da resposta e os model_urls quando a tarefa terminar. Vai usar ambos nos próximos passos.

Passo 2: Submeter uma Tarefa de Imagem para 3D

Com a sua chave de API pronta, inicie uma tarefa com um único pedido POST:

curl -X POST https://api.meshy.ai/openapi/v1/image-to-3d \
  -H "Authorization: Bearer $MESHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/your-image.png"
  }'

Vai receber uma resposta como esta:

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Esse valor result é o seu task_id — guarde-o. Vai precisar dele no próximo passo para verificar o progresso e obter o seu modelo.

Opcional: Para ser notificado automaticamente quando a tarefa terminar, adicione um campo webhook_url ao corpo JSON — por exemplo "webhook_url": "https://yourapp.com/webhooks/meshy". Veja o Passo 3, Opção B para como funciona.

Passo 3: Obter os Seus Resultados

A sua tarefa não termina instantaneamente — a Meshy processa-a em segundo plano. Tem duas formas de obter o resultado:

Opção A: Consultar o Estado (Mais Simples)

Envie um pedido GET a cada 5 segundos até que o status mude para SUCCEEDED:

curl https://api.meshy.ai/openapi/v1/image-to-3d/{task_id} \
  -H "Authorization: Bearer $MESHY_API_KEY"

A resposta é assim:

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_url": "https://assets.meshy.ai/.../model.glb",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb",
    "fbx": "https://assets.meshy.ai/.../model.fbx",
    "obj": "https://assets.meshy.ai/.../model.obj",
    "usdz": "https://assets.meshy.ai/.../model.usdz",
    "stl": "https://assets.meshy.ai/.../model.stl",
    "mtl": "https://assets.meshy.ai/.../model.mtl"
  },
  "thumbnail_url": "https://assets.meshy.ai/.../thumbnail.png",
  "consumed_credits": 30
}

Alguns campos que vale a pena conhecer:

• model_urls contém uma ligação de descarga para cada formato gerado. Por predefinição, isto inclui glb, fbx, obj, usdz, stl e mtl (o ficheiro de material que acompanha o obj).

• model_url é um atalho para a ligação GLB — útil quando só precisa de GLB.

• consumed_credits mostra quantos créditos a tarefa usou (é 0 para tarefas falhadas, pois os créditos são reembolsados).

• thumbnail_url está sempre presente e aponta para a miniatura da vista frontal.

• thumbnail_urls aparece apenas quando multi_view_thumbnails: true, e contém as vistas frontal, direita, traseira e esquerda.

• alpha_thumbnail_url aparece apenas quando alpha_thumbnail: true, e contém a miniatura com fundo transparente.

Valores possíveis de status: PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

Opção B: Webhook (Recomendado para Produção)

Se definiu um webhook_url no Passo 2, a Meshy enviará o objeto da tarefa concluída para o seu URL automaticamente — sem necessidade de consulta.

{
  "image_url": "https://example.com/your-image.png",
  "webhook_url": "https://yourapp.com/webhooks/meshy"
}

💡 Qual devo usar? A consulta periódica é adequada para protótipos e tarefas pontuais. Use webhooks em produção — é mais fiável e poupa chamadas de API.

Passo 4: Descarregar o Seu Modelo 3D

Assim que o status for SUCCEEDED, obtenha os URLs de descarga de model_urls e descarregue o formato de que precisa:

curl -o model.glb "https://assets.meshy.ai/.../model.glb"

A flag -o model.glb guarda o ficheiro no seu diretório de trabalho atual com esse nome — use um caminho completo (ex.: -o /path/to/model.glb) para o guardar noutro local.

Por predefinição, cada tarefa devolve GLB, FBX, OBJ, USDZ, STL e MTL (o ficheiro de material para OBJ). 3MF é opcional — só o obtém quando o solicita explicitamente através de target_formats (veja a tabela de parâmetros abaixo).

⚠️ As ligações expiram em 3 dias (planos Enterprise têm ligações permanentes). Descarregue e armazene os seus modelos prontamente — as ligações não funcionarão após a expiração, e terá de reexecutar a tarefa.

Pronto para usar este modelo na sua ferramenta DCC? Consulte o guia Bridge to Blender — a Meshy também tem pontes para Unity, Unreal, Maya e mais.

Como obter os melhores resultados de imagem para 3D?

• Use um único assunto claramente visível. Um objeto principal, centrado e totalmente em quadro, dá à IA a referência mais limpa — evite cenas movimentadas, cortes apertados e ângulos extremos.

• Prefira um fundo limpo e sem desordem. Fundos sólidos ou simples ajudam o modelo a separar o assunto do seu entorno.

• Use iluminação difusa e uniforme. Sombras fortes e realces intensos podem gravar detalhes enganadores na textura gerada.

• Comece com uma imagem de alta resolução e nítida. Mais detalhe na entrada resulta em mais detalhe na saída — entradas desfocadas ou de baixa resolução produzem modelos mais suaves.

Que linguagens de programação posso usar com a API Imagem para 3D?

Qualquer linguagem que consiga fazer pedidos HTTP — envia um POST com JSON e consulta com GET. Opções comuns:

• Python — use a biblioteca requests ou httpx

• JavaScript / TypeScript — use fetch (integrado) ou axios

• Go — use net/http da biblioteca padrão

• cURL — ótimo para testes rápidos a partir do terminal

Também pode encontrar exemplos de código prontos a copiar para todas as quatro no API Playground.

Quantos créditos custa uma tarefa de Imagem para 3D?

O custo depende da versão do modelo e se gera texturas. A configuração predefinida (meshy-6 com texturização) custa 30 créditos por tarefa:

Tarefas falhadas são reembolsadas automaticamente — consumed_credits devolve 0. Verifique sempre Preços para as taxas mais recentes.

Que parâmetros aceita a API Imagem para 3D?

Envie um POST para /openapi/v1/image-to-3d com estes parâmetros: Obrigatório (um de):

Opcional:

Próximos passos com a API Imagem para 3D

Agora tem o fluxo de trabalho completo: criar uma chave de API, submeter uma imagem, consultar ou usar um webhook para o resultado e, em seguida, descarregar o seu modelo. Os mesmos quatro passos escalam de um protótipo rápido a um pipeline de produção que transforma milhares de imagens em ativos 3D automaticamente. Obtenha a sua chave na página de definições da API e lance o seu primeiro modelo hoje. Prefere começar a partir de um prompt em vez de uma foto? Use a API Texto para Modelo 3D.

Perguntas Frequentes

Como converto uma imagem num modelo 3D através da API?

Envie um pedido POST para /openapi/v1/image-to-3d com o seu image_url e chave de API, depois consulte a tarefa (ou use um webhook) até que o seu status seja SUCCEEDED. A resposta devolve ligações de descarga para o modelo gerado. O fluxo completo de quatro passos — chave, submeter, obter, descarregar — está coberto no guia passo a passo acima.

Que formatos de saída (STL, GLB, OBJ) a API suporta?

Cada tarefa devolve GLB, FBX, OBJ, USDZ, STL e MTL por predefinição, com 3MF disponível mediante solicitação através de target_formats. GLB é melhor para web e RA, FBX e OBJ para ferramentas DCC e motores de jogo, USDZ para RA iOS e STL para impressão 3D.

Que formatos de imagem posso carregar?

A API Imagem para 3D suporta imagens JPG, JPEG e PNG até 100 MB — maior que o limite de 20 MB na interface do Workspace Meshy. Para os resultados mais precisos, use um PNG com fundo transparente ou branco limpo, o que ajuda a API a isolar o assunto e gerar um modelo 3D de maior qualidade.

Posso obter um modelo 3D texturizado da API?

Sim. A texturização está ativada por predefinição ("should_texture": true). Para adicionar mapas PBR (metálico, rugosidade, normal), defina "enable_pbr": true — no meshy-6/latest isto também inclui um mapa de emissão. Para uma textura de cor base a 4K, defina "hd_texture": true (suportado apenas em meshy-6/latest; os mapas PBR permanecem a 2K). Também pode orientar o estilo da textura com um texture_prompt ou um texture_image_url.

Posso gerar um modelo 3D pronto para impressão 3D (STL)?

Sim — o STL é gerado por predefinição, por isso uma conversão de imagem para 3D STL não precisa de parâmetros extra: basta obter model_urls.stl quando a tarefa terminar. Isto torna os fluxos de trabalho de imagem para impressão 3D simples, já que o STL é o formato padrão que os slicers esperam. Se só quiser STL, defina "target_formats": ["stl"] para ignorar os outros formatos e reduzir o tempo de geração.

Que planos incluem acesso à API?

O acesso à API está disponível nos planos Pro, Studio e Enterprise — é uma funcionalidade a partir do Pro. O plano gratuito Starter não inclui acesso à API. Consulte Preços para detalhes.

Quanto tempo são válidas as ligações de descarga?

As ligações de descarga são válidas por 3 dias nos planos Pro e Studio. Os clientes Enterprise obtêm ligações permanentes. Guarde os seus ficheiros prontamente — as ligações expiradas não podem ser recuperadas e terá de reexecutar a tarefa.

Posso executar várias tarefas ao mesmo tempo?

Sim, pedidos concorrentes são suportados. Se receber um erro 429 Too Many Requests, a sua conta atingiu o limite de taxa — implemente backoff exponencial e repita. Consulte a página Limites de Taxa para os limites do seu plano.

A tarefa mostra FAILED — o que faço?

Verifique task_error.message para a causa. Erros comuns:

Se o problema persistir, contacte o suporte Meshy.