Início rápido
Comece criando sua chave de API
Toda requisição neste guia precisa de uma. Criar uma chave leva segundos.
Crie sua chave de APIQuatro passos para seu primeiro modelo 3D, usando a API REST da Meshy.
Está usando um assistente de código com IA? Veja nossa página de Integração de IA — instale o Meshy MCP server para acesso via chamadas de ferramentas a partir do Claude Code, Cursor, Windsurf e outras ferramentas compatíveis com MCP, ou aponte um agente de chat simples para llms.txt.
1Obtenha sua chave de API
Crie uma chave de API na página API Keys da Developer Platform — você não poderá vê-la novamente após sair desta tela, então guarde-a em um local seguro. Toda requisição se autentica com um token Bearer no cabeçalho Authorization — veja Authentication.
Criar e gerenciar chaves de API requer um plano pago. Contas gratuitas recebem uma chave dedicada e integrada para testes no Playground, mas não podem criar ou gerenciar suas próprias chaves.

Dica de segurança: evite colar sua chave diretamente em scripts — em vez disso, armazene-a como uma variável de ambiente: export MESHY_API_KEY="msy_...".
2Faça sua primeira solicitação de Image to 3D
Exporte sua chave e, em seguida, crie sua primeira tarefa com Image to 3D. Está trabalhando a partir de um prompt de texto ou de várias fotos? Veja Text to 3D ou Multi-Image to 3D.
Export your key
export MESHY_API_KEY="<your-api-key>"
Execute isso no seu terminal (Terminal no macOS, Prompt de Comando ou PowerShell no Windows) — não em um navegador.
Todos os exemplos abaixo usam esta foto — substitua pela sua própria image_url para experimentar algo diferente.

Request
curl https://api.meshy.ai/openapi/v1/image-to-3d \
-X POST \
-H "Authorization: Bearer ${MESHY_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"image_url": "https://docs.meshy.ai/images/api/quick-start/source-photo.webp"
}'
3Verifique o status da tarefa
A tarefa é executada em segundo plano e geralmente leva alguns minutos. Faça polling no mesmo endpoint até que status seja SUCCEEDED, FAILED ou CANCELED, substituindo <task_id> abaixo pelo ID retornado na etapa 2. Para tempos típicos e quanto tempo esperar, consulte Ciclo de Vida da Tarefa.
Request
curl https://api.meshy.ai/openapi/v1/image-to-3d/<task_id> \
-H "Authorization: Bearer ${MESHY_API_KEY}"
Response — SUCCEEDED
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"status": "SUCCEEDED",
"progress": 100,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***",
"fbx": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.fbx?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"task_error": {
"message": ""
}
}
Polling não é o seu estilo? Use streaming via SSE ou um webhook para ser notificado no momento em que uma tarefa for concluída.
4Baixe o seu modelo
Obtenha o modelo a partir de model_urls na resposta acima. Cada formato (GLB, FBX, OBJ, USDZ, STL) é uma URL assinada e com tempo limitado — ou, em vez de usar a linha de comando, cole a URL diretamente na barra de endereços do seu navegador para baixá-la.
Download
curl -L "<model_urls.glb from the response above>" -o model.glb

Os arquivos são mantidos por 3 dias nos planos que não são Enterprise — consulte Retenção de Recursos.
Juntando tudo
Prefere um único script que faça tudo — criar, consultar, baixar?
Full script
import axios from 'axios';
import fs from 'fs';
const headers = { Authorization: `Bearer ${process.env.MESHY_API_KEY}` };
const imageUrl = 'https://docs.meshy.ai/images/api/quick-start/source-photo.webp';
// 1. Create the task
const { data: created } = await axios.post(
'https://api.meshy.ai/openapi/v1/image-to-3d',
{ image_url: imageUrl },
{ headers, timeout: 60_000 },
);
const taskId = created.result;
// 2. Poll until it finishes, for up to 60 minutes
const deadline = Date.now() + 60 * 60 * 1000;
let task;
while (true) {
const { data, headers: resHeaders } = await axios.get(
`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`,
{ headers, timeout: 30_000 },
);
task = data;
if (['SUCCEEDED', 'FAILED', 'CANCELED'].includes(task.status)) break;
if (Date.now() > deadline) {
// The task is still running. Check it again later with the same task ID instead of creating a new one.
throw new Error(`Task ${taskId} is still ${task.status}; check it again later`);
}
const waitSeconds = Number(resHeaders['retry-after']) || 5;
await new Promise((resolve) => setTimeout(resolve, waitSeconds * 1000));
}
// 3. Download the result (only if the task succeeded)
if (task.status !== 'SUCCEEDED') {
throw new Error(`Task ${task.status}: ${task.task_error?.message || 'unknown error'}`);
}
const { data: model } = await axios.get(task.model_urls.glb, { responseType: 'arraybuffer' });
fs.writeFileSync('model.glb', model);
console.log('Saved model.glb');
Explore common workflows
Personagem pronto para jogos
Faça o rigging de uma malha humanoide com um esqueleto para que esteja pronta para animar na Unity ou Unreal.
Learn more →Asset lowpoly
Defina model_type como smart-topology em Imagem para 3D para obter uma malha limpa e pronta para jogos.
Modelo para impressão 3D
Converta um modelo finalizado em um arquivo 3MF multicolorido, pronto para fatiar e imprimir.
Learn more →Próximos passos
- Prefere uma interface gráfica? Abra a Developer Platform — execute requisições no Playground, acompanhe o uso e os registros de requisições, e gerencie webhooks.
- Explore a referência completa da API para todos os endpoints.
- Aprenda com exemplos práticos: siga as receitas passo a passo no Cookbook e leia tutoriais e histórias de desenvolvimento no Developer Blog.
- Confira Preços, Limites de Taxa e Erros antes de ir para produção.
- Acompanhe o registro de alterações para atualizações e correções de bugs.
- Tem feedback ou está enfrentando problemas? Junte-se à nossa comunidade no Discord — adoraríamos ouvir você!