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

A API de Imagem para Modelo 3D transforma uma única foto em um modelo 3D pronto para produção em segundos—sem necessidade de modelagem manual. Modelar manualmente cada ativo é lento e caro, e para estúdios de jogos, aplicativos de RA e equipes de e-commerce, rapidamente se torna o gargalo que atrasa lançamentos. A API de imagem para modelo 3D da Meshy remove esse atrito: envie uma imagem, converta-a em um modelo 3D em segundos e baixe uma malha totalmente texturizada em formatos como GLB, FBX e OBJ. Este guia mostra todo o fluxo de trabalho—desde a criação da sua chave de API até o download do seu primeiro modelo—com código copiável que você pode executar em minutos.

O que é a API de Imagem para Modelo 3D?

Em sua essência, a API de Imagem para Modelo 3D é um endpoint REST alimentado pela IA de imagem para modelo 3D da Meshy. Você envia uma única imagem (JPG, JPEG ou PNG) como uma URL pública ou string base64, e a API retorna 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 de até 4K e miniaturas de pré-visualização de vários ângulos.

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

O que você precisa para usar a API de Imagem para 3D?

Você não precisa de muito para seguir este guia. Certifique-se de ter:

• Uma conta Meshy — cadastre-se gratuitamente se não tiver uma. Você gerará sua chave de API no painel na Etapa 1.

• Uma chave de API — usada para autenticar cada requisição. Vamos mostrar como criar uma, e você pode usar a chave de modo de teste gratuita para acompanhar sem gastar créditos.

• Uma imagem de entrada — um .jpg, .jpeg ou .png claro hospedado em uma URL publicamente acessível (ou codificado como base64). Um fundo limpo e um assunto claramente visível fornecem os melhores resultados.

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

É só isso—nenhuma experiência em modelagem 3D é necessária. Vamos começar.

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

Etapa 1: Configure Suas Configurações de API

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

• Chaves de API — gere e gerencie as chaves que autenticam suas requisições.

• Webhooks — seja notificado automaticamente quando suas tarefas terminarem.

• Uso — acompanhe seu saldo de créditos restante e consumo da API em tempo real.

Vamos ver cada uma delas.

Obtenha Sua Chave de API

Antes de fazer qualquer requisição, você precisa de uma chave de API para autenticar com segurança. Na página de configurações da API, clique em Gerar Chave de API. Cada chave segue o formato msy-<string-aleatória>.

Dica: Após gerada, armazene sua chave de API em algum lugar seguro (ex.: um gerenciador de senhas ou variável de ambiente). Trate-a como uma senha—nunca a envie para o controle de versão ou a exponha em código do lado do cliente.

Chave de API do Modo de Teste

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

msy_dummy_api_key_for_test_mode_12345678

Esta chave especial tem as seguintes características:

• Pode ser usada para fazer requisições a todos os endpoints da API Meshy.

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

• Todas as requisições válidas retornam o mesmo resultado de tarefa de amostra, independentemente dos parâmetros de entrada.

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

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

Configure Webhooks (Opcional)

Gerar um modelo 3D leva tempo, então, em vez de consultar repetidamente a API para verificar se uma tarefa foi concluída, você pode deixar a Meshy notificá-lo no momento em que ela terminar. É para isso que servem os webhooks.

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

Dica: Webhooks são a abordagem recomendada para produção. Eles reduzem chamadas de API desnecessárias e permitem que sua aplicação reaja aos resultados em tempo real. Para testes rápidos, a consulta (polling) ainda funciona bem. Para testar o código do webhook localmente, aponte-o para uma URL de proxy de um serviço como smee.io.

Experimente Sem Código — API Playground (Opcional)

Já tem sua chave de API? Antes de escrever qualquer código, você 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 sua chave de API (msy-xxxxxxxxxx)

2. Image — faça upload de um .jpg, .jpeg ou .png do seu computador

3. Clique em Send

O Playground envia a tarefa e consulta os resultados automaticamente. Quando terminar, você verá a pré-visualização do modelo 3D e os links de download diretamente no navegador—sem necessidade de código.

Dica profissional: O painel de requisição/resposta bruta à direita mostra exatamente o que a API envia e retorna. Você pode copiar o conteúdo diretamente—pegue o task_id da resposta e os model_urls assim que a tarefa terminar. Você usará ambos nas próximas etapas.

Etapa 2: Envie uma Tarefa de Imagem para 3D

Com sua chave de API pronta, inicie uma tarefa com uma única requisição 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"
  }'

Você receberá uma resposta como esta:

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

Esse valor result é seu task_id — salve-o. Você precisará dele na próxima etapa para verificar o progresso e recuperar 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 a Etapa 3, Opção B para saber como funciona.

Etapa 3: Obtenha Seus Resultados

Sua tarefa não termina instantaneamente—a Meshy a processa em segundo plano. Você tem duas maneiras de obter o resultado:

Opção A: Consulte o Status (Mais Simples)

Envie uma requisição 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 se parece com isto:

{
  "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 um link de download para cada formato gerado. Por padrão, isso inclui glb, fbx, obj, usdz, stl e mtl (o arquivo de material que acompanha o obj).

• model_url é um atalho para o link GLB—útil quando você só precisa do GLB.

• consumed_credits mostra quantos créditos a tarefa usou (é 0 para tarefas com falha, 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 você definiu um webhook_url na Etapa 2, a Meshy enviará o objeto da tarefa concluída para sua 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 (polling) é adequada para prototipagem e tarefas únicas. Use webhooks em produção—é mais confiável e economiza chamadas de API.

Etapa 4: Baixe Seu Modelo 3D

Assim que o status for SUCCEEDED, pegue as URLs de download de model_urls e baixe o formato que você precisa:

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

A flag -o model.glb salva o arquivo no seu diretório de trabalho atual com esse nome—use um caminho completo (ex.: -o /path/to/model.glb) para salvá-lo em outro lugar.

Por padrão, cada tarefa retorna GLB, FBX, OBJ, USDZ, STL e MTL (o arquivo de material para OBJ). 3MF é opcional—você só o obtém quando o solicita explicitamente via target_formats (veja a tabela de parâmetros abaixo).

⚠️ Os links expiram em 3 dias (planos Enterprise obtêm links permanentes). Baixe e armazene seus modelos prontamente—os links não funcionarão após a expiração, e você precisará executar a tarefa novamente.

Pronto para usar este modelo em sua ferramenta DCC? Consulte o guia Bridge to Blender—a Meshy também tem bridges 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, centralizado e totalmente no quadro, dá à IA a referência mais limpa—evite cenas movimentadas, cortes pesados e ângulos extremos.

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

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

• Comece com uma imagem de alta resolução e nítida. Mais detalhes na entrada resultam em mais detalhes na saída—imagens borradas ou de baixa resolução produzem modelos mais suaves.

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

Qualquer linguagem que possa fazer requisições HTTP—você 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 no terminal

Você também pode encontrar exemplos de código prontos para 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 você gera texturas. A configuração padrão (meshy-6 com texturização) custa 30 créditos por tarefa:

Tarefas com falha são reembolsadas automaticamente—consumed_credits retorna 0. Sempre verifique Preços para as taxas mais recentes.

Quais parâmetros a API de Imagem para 3D aceita?

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

Opcional:

Próximos passos com a API de Imagem para 3D

Agora você tem o fluxo de trabalho completo: crie uma chave de API, envie uma imagem, consulte ou use um webhook para o resultado e baixe 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. Pegue sua chave na página de configurações da API e envie seu primeiro modelo hoje. Prefere começar com um prompt em vez de uma foto? Use a API de Texto para Modelo 3D.

Perguntas Frequentes

Como faço para converter uma imagem em um modelo 3D via API?

Envie uma requisição POST para /openapi/v1/image-to-3d com seu image_url e chave de API, depois consulte a tarefa (ou use um webhook) até que seu status seja SUCCEEDED. A resposta retorna links de download para o modelo gerado. O fluxo completo de quatro etapas—chave, envio, recuperação, download—é abordado no guia passo a passo acima.

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

Cada tarefa retorna GLB, FBX, OBJ, USDZ, STL e MTL por padrão, com 3MF disponível mediante solicitação via target_formats. GLB é melhor para web e RA, FBX e OBJ para ferramentas DCC e engines de jogos, USDZ para RA no iOS e STL para impressão 3D.

Quais formatos de imagem posso enviar?

A API de Imagem para 3D suporta imagens JPG, JPEG e PNG de até 100 MB—maior que o limite de 20 MB na interface do Workspace da 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 padrão ("should_texture": true). Para adicionar mapas PBR (metálico, rugosidade, normal), defina "enable_pbr": true—no meshy-6/latest isso também inclui um mapa de emissão. Para uma textura de cor base em 4K, defina "hd_texture": true (suportado apenas em meshy-6/latest; mapas PBR permanecem em 2K). Você também pode direcionar 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—STL é gerado por padrão, então uma conversão de imagem para STL 3D não precisa de parâmetros extras: basta pegar model_urls.stl quando a tarefa for concluída. Isso torna os fluxos de trabalho de imagem para impressão 3D simples, já que STL é o formato padrão que os slicers esperam. Se você só quiser STL, defina "target_formats": ["stl"] para pular os outros formatos e reduzir o tempo de geração.

Quais planos incluem acesso à API?

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

Por quanto tempo os links de download são válidos?

Os links de download são válidos por 3 dias nos planos Pro e Studio. Clientes Enterprise obtêm links permanentes. Salve seus arquivos prontamente—links expirados não podem ser recuperados, e você precisará executar a tarefa novamente.

Posso executar várias tarefas ao mesmo tempo?

Sim, requisições simultâneas são suportadas. Se você receber um erro 429 Too Many Requests, sua conta atingiu o limite de taxa—implemente backoff exponencial e tente novamente. 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. Comuns:

Se o problema persistir, entre em contato com o suporte da Meshy.