Início rápido

Comece criando sua chave de API

Toda solicitação neste guia precisa de uma. Criar uma chave leva menos de um minuto.

Crie sua chave de API

Quatro passos para o seu primeiro modelo 3D, usando a Meshy REST API.


1Obtenha sua chave de API

Crie uma chave de API nas configurações da sua conta — você não poderá visualizá-la novamente após esta tela, então armazene-a em um local seguro. Toda solicitação autentica com um token Bearer no cabeçalho Authorization — veja Autenticação.

Abra as Configurações de API no menu API, depois crie sua chave


2Faça sua primeira solicitação de Imagem para 3D

Exporte sua chave, depois crie sua primeira tarefa com Imagem para 3D. Trabalhando a partir de um prompt de texto ou várias fotos? Veja Texto para 3D ou Multi-imagem para 3D.

Exporte sua chave

export MESHY_API_KEY="<your-api-key>"

Todo exemplo abaixo usa esta foto — substitua por seu próprio image_url para experimentar algo diferente.

Ilustração de personagem de fantasia usada como entrada de Imagem para 3D neste guia
Entrada de exemplo

Solicitação

POST
/openapi/v1/image-to-3d
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

As solicitações retornam um ID de tarefa imediatamente. Consulte o mesmo endpoint até que o status seja SUCCEEDED — substitua <task_id> abaixo pelo ID retornado na etapa 2.

Solicitação

GET
/openapi/v1/image-to-3d/:id
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": ""
  }
}

4Baixe seu modelo

Pegue o modelo de model_urls na resposta acima. Cada formato (GLB, FBX, OBJ, USDZ, STL) é uma URL assinada e com tempo limitado — ou pule a linha de comando e cole a URL diretamente na barra de endereços do seu navegador para baixá-lo.

Download

model_urls.glb
curl -L "<model_urls.glb from the response above>" -o model.glb
O modelo 3D resultante gerado a partir da foto de personagem de fantasia de exemplo
Seu resultado

Coloque tudo junto

Prefere um script que faça tudo — criar, consultar, baixar?

Script completo

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 },
);
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


Próximos passos