Início rápido
Comece por criar a sua chave de API
Cada pedido neste guia necessita de uma. Criar uma chave demora menos de um minuto.
Crie a sua chave de APIQuatro passos para o seu primeiro modelo 3D, usando a Meshy REST API.
A usar um assistente de codificação IA? Veja a nossa página de Integração de IA — instale o servidor MCP da Meshy para acesso a ferramentas de chamada 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 a sua chave de API
Crie uma chave de API a partir das definições da sua conta — não poderá visualizá-la novamente após este ecrã, por isso armazene-a num local seguro. Cada pedido autentica-se com um token Bearer no cabeçalho Authorization — veja Autenticação.
Dica de segurança: evite colar a sua chave diretamente em scripts — armazene-a como uma variável de ambiente: export MESHY_API_KEY="msy_...".
2Faça o seu primeiro pedido de Imagem para 3D
Exporte a sua chave, depois crie a sua primeira tarefa com Imagem para 3D. A trabalhar a partir de um prompt de texto ou várias fotos? Veja Texto para 3D ou Multi-imagem para 3D.
Exporte a sua chave
export MESHY_API_KEY="<your-api-key>"
Execute isto no seu terminal (Terminal no macOS, Prompt de Comando ou PowerShell no Windows) — não num navegador.
Cada exemplo abaixo usa esta foto — substitua pelo seu próprio image_url para experimentar algo diferente.
Pedido
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.cn/images/api/quick-start/source-photo.webp"
}'
3Verifique o estado da tarefa
Os pedidos retornam um ID de tarefa imediatamente. Consulte o mesmo endpoint até que o status seja SUCCEEDED — substitua <task_id> abaixo pelo ID retornado no passo 2.
Pedido
curl https://api.meshy.ai/openapi/v1/image-to-3d/<task_id> \
-H "Authorization: Bearer ${MESHY_API_KEY}"
Resposta — 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": ""
}
}
Não gosta de polling? Use streaming SSE ou um webhook para ser notificado assim que uma tarefa terminar.
4Descarregue o seu modelo
Obtenha o modelo a partir de model_urls na resposta acima. Cada formato (GLB, FBX, OBJ, USDZ, STL) é um URL assinado e com tempo limitado — ou evite a linha de comando e cole o URL diretamente na barra de endereços do seu navegador para descarregá-lo.
Descarregar
curl -L "<model_urls.glb from the response above>" -o model.glb
Os ficheiros são retidos por 3 dias em planos não empresariais — veja Retenção de Recursos.
Junte tudo
Prefere um script que faça tudo — criar, consultar, descarregar?
Script completo
import axios from 'axios';
import fs from 'fs';
const headers = { Authorization: `Bearer ${process.env.MESHY_API_KEY}` };
const imageUrl = 'https://docs.meshy.cn/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 },
);
const taskId = created.result;
// 2. Poll until it finishes
let task;
while (true) {
const { data } = await axios.get(`https://api.meshy.ai/openapi/v1/image-to-3d/${taskId}`, { headers });
task = data;
if (task.status === 'SUCCEEDED' || task.status === 'FAILED') break;
await new Promise((resolve) => setTimeout(resolve, 5000));
}
// 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 fluxos de trabalho comuns
Personagem pronto para jogo
Faça o rigging de uma malha humanoide com um esqueleto para que esteja pronta para animar no Unity ou Unreal.
Learn more →Recurso lowpoly
Defina model_type como lowpoly em Imagem para 3D para uma malha limpa e pronta para jogo.
Modelo para impressão 3D
Converta um modelo finalizado num ficheiro 3MF multicolor, pronto para fatiar e imprimir.
Learn more →Próximos passos
- Prefere uma interface gráfica? Experimente o API Playground — configure um pedido, execute-o e copie o código gerado.
- Navegue pela referência completa da API para cada endpoint.
- Verifique Preços, Limites de Taxa, e Erros antes de ir para produção.
- Veja o Registo de Alterações para atualizações e correções de bugs.
- Tem feedback ou enfrenta problemas? Junte-se à nossa comunidade no Discord — adoraríamos ouvir de si!