Início rápido

Esta é a referência da API para interagir programaticamente com o Meshy.

Usando um assistente de codificação de IA? Consulte nossa página de Integração de IA — instale o MCP server do Meshy para acesso por chamada 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.

A Meshy API fornece uma interface simples para gerar modelos 3D e texturas a partir de prompts de texto e imagens. Siga este guia para começar rapidamente.

Criar uma chave de API

Crie uma chave de API na página de configurações da API aqui, que você usará para autenticar suas solicitações com segurança. O formato da chave de API é msy-<random-string>.

Gerar chave de API

Depois de gerar uma chave de API, armazene-a em um local seguro.

Chave de API do modo de teste

Durante o desenvolvimento e os testes, você pode usar nossa chave de API do modo de teste para explorar a API sem consumir seus créditos:

msy_dummy_api_key_for_test_mode_12345678

Esta chave de API especial tem as seguintes características:

  • Ela pode ser usada para fazer solicitações a todos os endpoints da Meshy API
  • Nenhum crédito é consumido ao usar esta chave
  • Todas as solicitações válidas retornarão os mesmos resultados de tarefa de exemplo, independentemente dos parâmetros de entrada
  • A estrutura de dados da resposta corresponderá exatamente à API de produção
  • Perfeita para testar sua integração de API antes de mudar para sua chave de API real

A chave de API do modo de teste é apenas para fins de desenvolvimento. Para uso em produção, use sua própria chave de API.

Faça sua primeira solicitação de API "Texto para 3D"

Neste exemplo, vamos gerar um modelo 3D a partir de um prompt de texto usando o endpoint text-to-3d. O processo envolve duas etapas: a etapa de preview e a etapa de refinamento. Na etapa de preview, uma malha base é gerada sem textura aplicada, permitindo avaliar a geometria. Na etapa de refinamento, a malha de preview recebe textura com base no prompt de texto.

Vamos mostrar como fazer essas solicitações em um script Python.

Preview

O Meshy fornece um conjunto de endpoints de API REST. Você pode usá-los com qualquer cliente HTTP de sua escolha. Independentemente de qual API você chamar, a chave de API é sempre passada como um cabeçalho chamado Authorization. Lembre-se de exportar sua chave de API como uma variável de ambiente chamada MESHY_API_KEY antes de usar este script.

Os parâmetros principais para a solicitação de preview são mode, que é sempre "preview", e prompt, uma descrição do modelo de que você precisa. Neste exemplo, também especificamos should_remesh, mas ele é opcional.

api_request.py

import requests
import os
import time

headers = {
  "Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}

# 1. Generate a preview model and get the task ID

generate_preview_request = {
  "mode": "preview",
  "prompt": "a monster mask",
  "should_remesh": True,
}

generate_preview_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_preview_request,
)

generate_preview_response.raise_for_status()

preview_task_id = generate_preview_response.json()["result"]

print("Preview task created. Task ID:", preview_task_id)

Isso conclui a chamada de API de preview.

Tenha em mente que a Meshy API adota um modelo de execução assíncrona, o que significa que, quando você cria uma tarefa, o endpoint da API retorna apenas um ID de tarefa. Em seguida, você deve consultar o endpoint de status da tarefa com esse ID para verificar se a tarefa foi concluída.

api_request.py

# 2. Poll the preview task status until it's finished

preview_task = None

while True:
  preview_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
    headers=headers,
  )

  preview_task_response.raise_for_status()

  preview_task = preview_task_response.json()

  if preview_task["status"] == "SUCCEEDED":
    print("Preview task finished.")
    break

  print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

Depois que a tarefa for concluída, você poderá acessar as URLs do modelo na resposta. Vamos baixar o modelo a partir do campo model_urls na resposta.

api_request.py

# 3. Download the preview model in glb format

preview_model_url = preview_task["model_urls"]["glb"]

preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()

with open("preview_model.glb", "wb") as f:
  f.write(preview_model_response.content)

print("Preview model downloaded.")

Se tudo funcionar até aqui, seu preview_model.glb deve se parecer com isto. Ele não será uma correspondência exata, devido à aleatoriedade intrínseca no pipeline de IA.

Modelo de preview

Refinamento

Vamos prosseguir para a etapa de refinamento. Para iniciar a solicitação de refinamento, forneça o ID da tarefa de preview como um parâmetro de entrada.

api_request.py

# 4. Generate a refined model and get the task ID

generate_refined_request = {
  "mode": "refine",
  "preview_task_id": preview_task_id,
}

generate_refined_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_refined_request,
)

generate_refined_response.raise_for_status()

refined_task_id = generate_refined_response.json()["result"]

print("Refined task created. Task ID:", refined_task_id)

# 5. Poll the refined task status until it's finished

refined_task = None

while True:
  refined_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
    headers=headers,
  )

  refined_task_response.raise_for_status()

  refined_task = refined_task_response.json()

  if refined_task["status"] == "SUCCEEDED":
    print("Refined task finished.")
    break

  print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

# 6. Download the refined model in glb format

refined_model_url = refined_task["model_urls"]["glb"]

refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()

with open("refined_model.glb", "wb") as f:
  f.write(refined_model_response.content)

print("Refined model downloaded.")

O modelo 3D refined_model.glb agora está totalmente com textura ✨.

Modelo refinado

Juntando tudo

Aqui está o código completo para usar a API Texto para 3D.

api_request.py

import requests
import os
import time

headers = {
  "Authorization": f"Bearer {os.environ['MESHY_API_KEY']}"
}

# 1. Generate a preview model and get the task ID

generate_preview_request = {
  "mode": "preview",
  "prompt": "a monster mask",
  "should_remesh": True,
}

generate_preview_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_preview_request,
)

generate_preview_response.raise_for_status()

preview_task_id = generate_preview_response.json()["result"]

print("Preview task created. Task ID:", preview_task_id)

# 2. Poll the preview task status until it's finished

preview_task = None

while True:
  preview_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{preview_task_id}",
    headers=headers,
  )

  preview_task_response.raise_for_status()

  preview_task = preview_task_response.json()

  if preview_task["status"] == "SUCCEEDED":
    print("Preview task finished.")
    break

  print("Preview task status:", preview_task["status"], "| Progress:", preview_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

# 3. Download the preview model in glb format

preview_model_url = preview_task["model_urls"]["glb"]

preview_model_response = requests.get(preview_model_url)
preview_model_response.raise_for_status()

with open("preview_model.glb", "wb") as f:
  f.write(preview_model_response.content)

print("Preview model downloaded.")

# 4. Generate a refined model and get the task ID

generate_refined_request = {
  "mode": "refine",
  "preview_task_id": preview_task_id,
}

generate_refined_response = requests.post(
  "https://api.meshy.ai/openapi/v2/text-to-3d",
  headers=headers,
  json=generate_refined_request,
)

generate_refined_response.raise_for_status()

refined_task_id = generate_refined_response.json()["result"]

print("Refined task created. Task ID:", refined_task_id)

# 5. Poll the refined task status until it's finished

refined_task = None

while True:
  refined_task_response = requests.get(
    f"https://api.meshy.ai/openapi/v2/text-to-3d/{refined_task_id}",
    headers=headers,
  )

  refined_task_response.raise_for_status()

  refined_task = refined_task_response.json()

  if refined_task["status"] == "SUCCEEDED":
    print("Refined task finished.")
    break

  print("Refined task status:", refined_task["status"], "| Progress:", refined_task["progress"], "| Retrying in 5 seconds...")
  time.sleep(5)

# 6. Download the refined model in glb format

refined_model_url = refined_task["model_urls"]["glb"]

refined_model_response = requests.get(refined_model_url)
refined_model_response.raise_for_status()

with open("refined_model.glb", "wb") as f:
  f.write(refined_model_response.content)

print("Refined model downloaded.")

Copie e cole o código em um script Python e execute-o.

Run the script

python api_request.py

Você deve ver uma saída no seu terminal como a seguinte:

Executar o script

Próximos passos

  • Prefere experimentar endpoints sem escrever código primeiro? Use o API Playground para configurar e executar uma solicitação e, em seguida, copie o snippet gerado.
  • Você pode encontrar a referência completa da API na seção "Endpoints da API", que fornece informações detalhadas sobre cada API.
  • Explore detalhes sobre Preços, Limites de taxa e como solucionar erros comuns.
  • Não se esqueça de conferir regularmente nosso registro de alterações para atualizações e correções de bugs.
  • Tem feedback ou está enfrentando problemas? Entre na nossa comunidade do Discord - adoraríamos ouvir você!