Início rápido

Comece criando sua chave de API

Toda solicitação neste guia precisa de uma. Criar uma chave leva segundos.

Crie sua chave de API

Quatro etapas para seu primeiro modelo 3D, usando a API REST da Meshy.


1Obtenha sua chave de API

Crie uma chave de API na página API Keys na Plataforma de Desenvolvedores — você não poderá visualizá-la novamente após esta tela, então guarde-a em um local seguro. Toda solicitação se autentica com um token Bearer no cabeçalho Authorization — veja Autenticação.

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


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

Exporte sua chave e, em seguida, crie sua primeira tarefa com Imagem para 3D. Está trabalhando a partir de um prompt de texto ou de várias fotos em vez disso? Veja Texto para 3D ou Multi-imagem para 3D.

Export your key

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

Todo exemplo abaixo usa esta foto — substitua por sua própria image_url para tentar algo diferente.

Sample fantasy character illustration used as the Image to 3D input in this guide
Sample input

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

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

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

4Baixe seu modelo

Obtenha o modelo em 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á-la.

Download

model_urls.glb
curl -L "<model_urls.glb from the response above>" -o model.glb
The resulting 3D model generated from the sample fantasy character photo
Your result

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