lowpoly será descontinuado em 30 de out. de 2026. Troque de modelo antes dessas datas para evitar erros nas solicitações. Ver todas as descontinuações

Início rápido

Comece criando sua chave de API

Toda requisição deste guia precisa de uma. Criar uma chave leva segundos.

Crie sua chave de API

Crie seu primeiro modelo 3D com a API REST da Meshy em quatro etapas, desde a criação de uma chave de API até o download do modelo.


1Obtenha sua chave de API

Crie uma chave de API na página API Keys da Plataforma de Desenvolvedores. Você não pode visualizar a chave novamente depois de sair dessa tela, então guarde-a em um local seguro. Envie-a em todas as requisições como um token Bearer no cabeçalho Authorization. Veja Autenticação.

Você precisa de um plano pago para criar e gerenciar chaves de API. No plano Free, você não pode criar chaves próprias, e o Playground usa uma chave integrada para testes.

Abra a página API Keys na Plataforma de Desenvolvedores e, em seguida, crie sua chave


2Criar uma tarefa de Imagem para 3D

Envie uma imagem para Imagem para 3D. Para começar a partir de um prompt de texto ou de várias fotos, use Texto para 3D ou Multi-imagem para 3D.

Primeiro, armazene sua chave em uma variável de ambiente:

Export your key

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

Os exemplos a seguir usam todos esta foto. Para experimentar outra imagem, altere image_url.

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

Request

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

A tarefa é executada em segundo plano e geralmente leva alguns minutos. Obtenha a tarefa no mesmo endpoint até que status seja SUCCEEDED, FAILED ou CANCELED. Na solicitação a seguir, substitua <task_id> pelo ID retornado na etapa 2. Entre as solicitações, aguarde o número de segundos indicado no cabeçalho Retry-After.

Para saber os tempos de processamento típicos e quanto tempo esperar antes de desistir, consulte Ciclo de vida da tarefa.

Request

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}"

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": ""
  }
}

Se a tarefa falhar, status será FAILED, e task_error informará o motivo. Corrija a entrada ou crie outra tarefa. Consulte Erros.


4Baixe seu modelo

Os arquivos estão em model_urls na resposta anterior. Cada formato (GLB, FBX, OBJ, USDZ e STL) tem uma URL assinada que funciona por um tempo limitado. Você também pode colar a URL no seu navegador para baixar o arquivo.

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 exemplo do personagem de fantasia
Seu resultado

Juntando tudo

Este script cria a tarefa, aguarda sua conclusão e baixa o modelo.

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, 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


Próximos passos