Início rápido
Esta é a referência da API para interagir programaticamente com Meshy.
Está a usar um assistente de programação de IA? Consulte a nossa página de Integração de IA — instale o Meshy MCP server para acesso por chamadas 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 definições da API aqui, que irá usar para autenticar os seus pedidos de forma segura. O formato da chave de API é msy-<random-string>.
Depois de gerar uma chave de API, guarde-a num local seguro.
Chave de API do modo de teste
Durante o desenvolvimento e os testes, pode usar a nossa chave de API do modo de teste para explorar a API sem consumir os seus créditos:
msy_dummy_api_key_for_test_mode_12345678
Esta chave de API especial tem as seguintes características:
- Pode ser usada para fazer pedidos a todos os endpoints da Meshy API
- Não são consumidos créditos ao usar esta chave
- Todos os pedidos válidos devolverão os mesmos resultados de tarefa de exemplo, independentemente dos parâmetros de entrada
- A estrutura dos dados da resposta corresponderá exatamente à API de produção
- Perfeita para testar a sua integração da API antes de mudar para a sua chave de API real
A chave de API do modo de teste destina-se apenas a fins de desenvolvimento. Para uso em produção, use a sua própria chave de API.
Faça o seu primeiro pedido à API "Texto para 3D"
Neste exemplo, vamos gerar um modelo 3D a partir de um prompt de texto usando o text-to-3d endpoint. O processo envolve duas fases: a fase de pré-visualização e a fase de refinamento. Na fase de pré-visualização, é gerada uma malha base sem textura aplicada, permitindo-lhe avaliar a geometria. Na fase de refinamento, a malha de pré-visualização recebe textura com base no prompt de texto.
Vamos mostrar-lhe como fazer estes pedidos num script Python.
Pré-visualização
A Meshy fornece um conjunto de endpoints de REST API. Pode usá-los com qualquer cliente HTTP à sua escolha. Independentemente da API que chamar, a chave de API é sempre passada como um cabeçalho chamado Authorization. Lembre-se de exportar a sua chave de API como uma variável de ambiente chamada MESHY_API_KEY antes de usar este script.
Os parâmetros principais para o pedido de pré-visualização são mode, que é sempre "preview", e prompt, uma descrição do modelo de que precisa. Neste exemplo, também especificámos should_remesh, mas é 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)
Isto conclui a chamada à API de pré-visualização.
Tenha em conta que a Meshy API adota um modelo de execução assíncrona, o que significa que, quando cria uma tarefa, o endpoint da API devolve apenas um ID da tarefa. Em seguida, tem de consultar periodicamente o endpoint de estado da tarefa com este ID para verificar se a tarefa terminou.
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)
Assim que a tarefa terminar, poderá aceder aos URLs do modelo a partir da respetiva resposta. Vamos descarregar 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 correr bem até aqui, o seu preview_model.glb deverá ter um aspeto semelhante a este. Não será uma correspondência exata, devido à aleatoriedade intrínseca no pipeline de IA.
Refinamento
Vamos avançar para a fase de refinamento. Para iniciar o pedido de refinamento, forneça o ID da tarefa de pré-visualização como 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 está agora totalmente texturizado ✨.
Juntar 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 num script Python e execute-o.
Run the script
python api_request.py
Deverá ver no seu terminal uma saída como a seguinte:
Próximos passos
- Prefere experimentar endpoints sem escrever código primeiro? Use o API Playground para configurar e executar um pedido e, em seguida, copie o snippet gerado.
- Pode encontrar a referência completa da API na secção "Endpoints da API", que fornece informações detalhadas sobre cada API.
- Explore detalhes sobre Preços, Limites de taxa e como resolver erros comuns.
- Não se esqueça de consultar regularmente o nosso registo de alterações para atualizações e correções de erros.
- Tem feedback ou está a enfrentar problemas? Junte-se à nossa comunidade no Discord - gostaríamos muito de ouvir a sua opinião!