API de Texto para 3D
Gere modelos 3D a partir de prompts de texto em sua própria aplicação.
O Texto para 3D funciona em duas etapas. Primeiro, crie uma tarefa de preview (mode: "preview") para gerar uma malha 3D sem textura, para que você possa verificar o formato. Em seguida, envie o ID da tarefa de preview bem-sucedida para uma tarefa de refine (mode: "refine") para texturizar a malha. Ambas as etapas usam o mesmo endpoint.
Create a Text to 3D preview task
Cria uma tarefa de preview de Texto para 3D, que gera uma malha 3D sem textura (apenas geometria) a partir de um prompt de texto. Essa é a primeira etapa do fluxo de trabalho de duas etapas. Após o preview ser concluído com sucesso, envie o ID dessa tarefa em uma tarefa de refine para texturizar a malha. Veja Criar uma tarefa de refine de Texto para 3D. Para o esquema completo da resposta, veja O objeto de tarefa de Texto para 3D.
A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa geralmente leva, veja Tempos de processamento.
Request
# Simple preview with required params only
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "preview",
"prompt": "a monster mask"
}'
# Preview with Ultra 4K geometry, remesh, and A-pose
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "preview",
"prompt": "a futuristic robot warrior",
"ai_model": "meshy-7.1",
"geometry_resolution": "4k",
"should_remesh": true,
"target_polycount": 100000,
"pose_mode": "a-pose",
"target_formats": ["glb"]
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Parâmetros
- Name
- mode
- Type
- string
- Obrigatório
- Description
A etapa do fluxo de trabalho de duas etapas. Envie
previewpara criar uma tarefa de preview.
- Name
- prompt
- Type
- string
- Obrigatório
- Description
Texto que descreve o objeto a ser gerado, com até 800 caracteres. Um texto mais longo retorna
400.
- Name
- model_type
- Type
- string
- padrão standard
- Description
O tipo de malha 3D a ser gerada.
Valores disponíveis:
standard: uma malha 3D de alto detalhesmart-topology: uma malha Smart Topology. Escolha o modelo comai_model(meshy-t2oumeshy-t2.5).
Com
smart-topology, o Meshy ignorashould_remeshedecimation_mode, e aceita apenastopology: triangle.
- Name
- ai_model
- Type
- string
- padrão latest
- Description
O modelo de IA que gera o modelo 3D. Os valores disponíveis dependem de
model_type.Modelos standard (
model_type: standard):meshy-6-litemeshy-6meshy-7.1latest: Meshy 7.1meshy-7(obsoleto): enviemeshy-7.1em vez disso. Ele será descontinuado em 31 de dezembro de 2026.
Modelos Smart Topology (
model_type: smart-topology):meshy-t2: topology mais limpa, partes nativamente separadas, saída em triângulos e uma contagem de faces definida por você comtarget_polycountmeshy-t2.5(padrão): detalhe mais nítido para assets de jogos, saída em triângulos e uma contagem de faces definida por você comtarget_polycount
Veja Modelos para saber qual modelo se encaixa no seu projeto, como um personagem de jogo ou uma impressão 3D.
- Name
- geometry_resolution
- Type
- string
- padrão standard
- Description
A passagem de geração de geometria. Aplica-se apenas a tarefas de preview. Um refine com esse parâmetro retorna
400.Valores disponíveis:
standard2k: executa a passagem Ultra em 2048³4k: executa a passagem Ultra em 4096³, para um detalhe de superfície mais fino
2krequermeshy-7.1,latest, ou omeshy-7obsoleto.4krequermeshy-7.1oulatest. Outros modelos retornam400.
- Name
- ultra_mode
- Type
- boolean
- ⚠ obsoleto
- padrão false
- Description
Envie
geometry_resolutionem vez disso.ultra_mode: trueé o mesmo quegeometry_resolution: "2k".
- Name
- should_remesh
- Type
- boolean
- padrão true (meshy-6-lite), false (other models)
- Description
Se deve refazer a malha do modelo após a geração. Para o modelo 3D de mais alta qualidade, envie
false.
should_remesh = true- Name
- topology
- Type
- string
- padrão triangle
- Description
O tipo de face do modelo com malha refeita.
Valores disponíveis:
quad: uma malha predominantemente quadtriangle: uma malha de triângulos decimada
A saída do Smart Topology é apenas em triângulos. Enviar
quadcomai_modelmeshy-t2oumeshy-t2.5retorna400.
- Name
- decimation_mode
- Type
- integer
- Description
Contagem de faces adaptativa, por nível. Quando você define isso, o Meshy ignora
target_polycount.Valores disponíveis:
1: ultra2: alto3: médio4: baixo
- Name
- target_polycount
- Type
- integer
- Description
O número de faces desejado. O resultado pode diferir do alvo, dependendo da geometria. Isso se aplica em dois casos separados:
- Remesh: com
should_remesh: trueem um modelostandard. O Meshy refaz a malha (decima) para cerca dessa contagem. Se você definirdecimation_mode, o Meshy o utiliza e ignoratarget_polycount. - Smart Topology: com
model_type: smart-topologyeai_modelmeshy-t2oumeshy-t2.5. O Meshy gera o modelo diretamente com essa contagem de faces. Nenhum remesh é executado, e você não precisa deshould_remesh.
A tabela a seguir mostra o intervalo e o padrão para cada caso:
Caso Intervalo Padrão Remesh 100a30000030000meshy-t2100a150004000meshy-t2.5100a3000015000Um valor fora do intervalo retorna
400.Para um asset de jogo low-poly, use um modelo Smart Topology em vez de refazer a malha de um modelo standard. Veja Modelos.
- Remesh: com
- Name
- symmetry_mode
- Type
- string
- ⚠ obsoleto
- padrão auto
- Description
Não inclua. Esse parâmetro não afeta a saída.
Valores disponíveis:
off: desativa a simetriaauto: aplica simetria com base na geometria de entradaon: impõe simetria durante a geração
- Name
- pose_mode
- Type
- string
- Description
A pose para um modelo de personagem,
a-poseout-pose. Para não ter pose nenhuma, não incluapose_modenemis_a_t_pose.
- Name
- is_a_t_pose
- Type
- boolean
- ⚠ obsoleto
- padrão false
- Description
Envie
pose_modeem vez disso. Se deve gerar o modelo em pose A ou pose T.
- Name
- art_style
- Type
- string
- ⚠ obsoleto
- padrão realistic
- Description
Não inclua. O Meshy o ignora.
- Name
- moderation
- Type
- boolean
- padrão false
- Description
Se deve verificar o
promptem busca de conteúdo nocivo antes de gerar. Se o Meshy detectar conteúdo nocivo, a requisição retorna400e o Meshy não cria a tarefa.
- Name
- target_formats
- Type
- string[]
- Description
Os formatos de arquivo a serem gerados. O Meshy gera e retorna apenas esses formatos, o que pode encurtar a tarefa. Se você não incluir isso, o Meshy gera todos os formatos, exceto
3mf, que ele gera apenas quando solicitado.Valores disponíveis:
glbobjfbxstlusdz3mf
- Name
- alpha_thumbnail
- Type
- boolean
- padrão false
- Description
Se também deve renderizar um preview com fundo transparente (RGBA), retornado em
alpha_thumbnail_urlquando você obtém a tarefa.thumbnail_urlnão muda.
- Name
- auto_size
- Type
- boolean
- padrão false
- Description
Se deve estimar a altura real do objeto usando visão computacional de IA e redimensionar o modelo de acordo. O Meshy coloca a origem na parte inferior, a menos que você defina
origin_at.
auto_size = true- Name
- origin_at
- Type
- string
- padrão bottom
- Description
Onde colocar a origem do modelo,
bottomoucenter.
Retornos
O campo result da resposta contém o ID da nova tarefa de Texto para 3D.
Modos de falha
- Name
400 - Bad Request- Description
A requisição não pode ser executada. A mensagem de erro indica qual problema foi encontrado. Por exemplo:
- Parâmetro ausente: Um parâmetro obrigatório, como
promptoumode, está ausente. - Prompt muito longo:
promptexcede o limite de caracteres. - Modelo não suportado para Ultra:
geometry_resolutioné2kou4k, com umai_modelque não pode executá-lo.
Corrija a requisição e envie-a novamente. Veja Erros.
- Parâmetro ausente: Um parâmetro obrigatório, como
- Name
401 - Unauthorized- Description
A chave de API está ausente ou é inválida. Verifique o cabeçalho
Authorization.
- Name
402 - Payment Required- Description
Por exemplo:
- Créditos insuficientes: A conta não tem créditos suficientes para essa tarefa, ou a conta atingiu um limite de créditos. Verifique seu saldo de créditos e tente novamente.
- Plano gratuito: Criar uma tarefa requer um plano pago. Faça upgrade do seu plano nas configurações de assinatura e tente novamente.
- Name
403 - Forbidden- Description
A moderação de conteúdo bloqueou o prompt ou uma imagem de entrada. Altere a entrada e tente novamente.
- Name
429 - Too Many Requests- Description
Você excedeu seu limite de taxa. Aguarde e tente novamente. Veja Limites de taxa.
Criar uma tarefa de refine do Texto para 3D
Cria uma tarefa de refine do Texto para 3D, que texturiza a malha de uma tarefa de preview concluída. Envie o ID de uma tarefa de preview bem-sucedida como preview_task_id. Veja Criar uma tarefa de preview do Texto para 3D. Esta é a segunda etapa do fluxo de trabalho de duas etapas.
A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa costuma levar, veja Tempos de processamento.
Request
# Basic refine task
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "refine",
"preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"enable_pbr": true
}'
# Refine with auto-size and GLB format
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "refine",
"preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"target_formats": ["glb"],
"auto_size": true
}'
# Refine with Meshy N1 from the preview's stored reference image
curl https://api.meshy.ai/openapi/v2/text-to-3d \
-H 'Authorization: Bearer ${YOUR_API_KEY}' \
-H 'Content-Type: application/json' \
-d '{
"mode": "refine",
"preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"ai_model": "meshy-n1"
}'
Response
{
"result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
Parâmetros
- Name
- mode
- Type
- string
- Obrigatório
- Description
A etapa do fluxo de trabalho de duas etapas. Envie
refinepara criar uma tarefa de refine.
- Name
- preview_task_id
- Type
- string
- Obrigatório
- Description
O ID da tarefa de preview a ser texturizada. A tarefa de preview deve ter o status
SUCCEEDED.
- Name
- enable_pbr
- Type
- boolean
- padrão false
- Description
Se também deve gerar mapas PBR (metálico, rugosidade e normal) junto com a cor base.
Com
ai_modelmeshy-6, o Meshy também gera um mapa de emissão, exceto emtexture_resolution: 8k.meshy-6-lite,meshy-7elatestnão geram um mapa de emissão. O mesmo vale para um refine de um previewmeshy-t2oumeshy-t2.5que não definaai_model. Comai_model: meshy-n1,trueretorna400.
- Name
- texture_resolution
- Type
- string
- padrão 2k
- Description
A resolução da textura de cor base. Aplica-se apenas a tarefas de refine. Um preview com este parâmetro retorna
400.Valores disponíveis:
2k: 2048×20484k: 4096×40968k: 8192×8192
Resoluções mais altas capturam mais detalhes de superfície.
4ke8kexigemai_modelmeshy-6,meshy-7oulatest. Commeshy-n1, retornam400. Em8k, o Meshy não gera um mapa de emissão.
- Name
- hd_texture
- Type
- boolean
- ⚠ obsoleto
- padrão false
- Description
Envie
texture_resolutionem vez disso.hd_texture: trueé o mesmo quetexture_resolution: "4k". Se você enviar ambos, o Meshy usatexture_resolution.
- Name
- texture_prompt
- Type
- string
- Description
Texto que orienta a texturização, com até 800 caracteres. Um texto mais longo retorna
400. Envietexture_promptoutexture_image_url, não ambos. Se você enviar ambos, o Meshy usatexture_prompt. Comai_model: meshy-n1, enviá-lo retorna400.
- Name
- texture_image_url
- Type
- string
- Description
Uma imagem 2D que orienta a texturização, como uma URL pública ou um Data URI codificado em base64, como
data:image/jpeg;base64,<seus dados de imagem codificados em base64>.A imagem deve ser um arquivo
.jpg,.jpeg,.pngou.webpde no máximo 20 MB, com pelo menos 32 pixels em cada lado e no máximo 178.956.970 pixels (largura × altura).Com
ai_model: meshy-n1, o Meshy texturiza a partir dessa imagem como a visão frontal.A texturização a partir de uma imagem pode não funcionar bem quando a forma na imagem difere muito do modelo.
- Name
- ai_model
- Type
- string
- padrão inherited from the preview task
- Description
O modelo de IA que texturiza a malha. A malha vem do preview, então, em um refine,
ai_modelescolhe apenas o modelo de textura.Valores disponíveis:
meshy-7: Meshy 7latest: o modelo de textura mais recente, atualmente o Meshy 7meshy-6: Meshy 6meshy-6-lite: Meshy 6 Litemeshy-n1: uma textura de cor base em 2K a partir apenas de uma imagem de referência. Sem prompt de texto, sem mapas PBR, sem 4K ou 8K.
Os valores acima são modelos de textura. Omita para texturizar com o modelo que corresponde ao preview. Envie um valor para substituí-lo.
Com
meshy-n1, o Meshy texturiza a partir detexture_image_url. Sem ele, o Meshy usa a imagem de referência que um previewmeshy-7.1oulatestarmazena. Qualquer outro preview retorna400, a menos que você envietexture_image_url. O preview pode ter no máximo 7.999.999 triângulos. Um preview remesh para quads retorna400.
- Name
- moderation
- Type
- boolean
- padrão false
- Description
Se deve verificar
texture_promptetexture_image_urlem busca de conteúdo nocivo antes de gerar. Se o Meshy detectar conteúdo nocivo, a solicitação retorna400e o Meshy não cria a tarefa.
- Name
- remove_lighting
- Type
- boolean
- padrão true
- Description
Se deve remover realces e sombras da textura de cor base. O resultado mais limpo funciona melhor sob iluminação personalizada.
Tem efeito apenas quando
ai_modelémeshy-6.meshy-7elatestaceitam o parâmetro e o ignoram, assim como um refine de um previewmeshy-t2oumeshy-t2.5que não definaai_model. Enviá-lo commeshy-6-literetorna400. Commeshy-n1,trueretorna400.
- Name
- target_formats
- Type
- string[]
- Description
Os formatos de arquivo a serem gerados. O Meshy gera e retorna apenas esses formatos, o que pode encurtar a tarefa. Se você omitir, o Meshy gera todos os formatos, exceto
3mf, que só gera quando solicitado.Valores disponíveis:
glbobjfbxstlusdz3mf
- Name
- alpha_thumbnail
- Type
- boolean
- padrão false
- Description
Se também deve renderizar um preview com fundo transparente (RGBA), retornado em
alpha_thumbnail_urlquando você obtiver a tarefa.thumbnail_urlnão muda.
- Name
- auto_size
- Type
- boolean
- padrão false
- Description
Se deve estimar a altura real do objeto no mundo real usando visão de IA e redimensionar o modelo de acordo. O Meshy coloca a origem na parte inferior, a menos que você defina
origin_at.
auto_size = true- Name
- origin_at
- Type
- string
- padrão bottom
- Description
Onde colocar a origem do modelo,
bottomoucenter.
Retornos
O campo result da resposta contém o ID da nova tarefa de Texto para 3D.
Modos de falha
- Name
400 - Bad Request- Description
A solicitação não pode ser executada. A mensagem de erro indica qual problema foi encontrado. Por exemplo:
- ID de tarefa inválido:
preview_task_idé inválido ou não corresponde a nenhuma de suas tarefas de preview. - Tarefa não está pronta: A tarefa de preview ainda não foi concluída com sucesso.
- Incompatibilidade de modelo: O modelo de IA da tarefa de preview não funciona com o modelo de refine solicitado.
- Modelo não suportado para remove_lighting:
remove_lightingfoi enviado comai_model: "meshy-6-lite". - Nenhuma imagem de referência para o Meshy N1:
ai_model: meshy-n1foi enviado semtexture_image_url, e o preview não possui nenhuma imagem de referência que o Meshy N1 possa usar. Envietexture_image_url. - Preview em quads para o Meshy N1:
ai_model: meshy-n1foi enviado para um preview remesh para quads. Faça o refine com outroai_model. - Triângulos demais para o Meshy N1: Com
ai_model: meshy-n1, o preview tem mais de 7.999.999 triângulos. Faça o refine com outroai_model. - Opção não suportada para o Meshy N1:
ai_model: meshy-n1foi enviado com uma destas opções:texture_promptenable_pbr: truetexture_resolutionde4kou8khd_texture: truesemtexture_resolutionremove_lighting: true
Corrija a solicitação e envie-a novamente. Veja Erros.
- ID de tarefa inválido:
- Name
401 - Unauthorized- Description
A chave de API está ausente ou é inválida. Verifique o cabeçalho
Authorization.
- Name
402 - Payment Required- Description
Por exemplo:
- Créditos insuficientes: A conta não tem créditos suficientes para esta tarefa, ou a conta atingiu um limite de créditos. Verifique seu saldo de créditos e tente novamente.
- Plano gratuito: Criar uma tarefa requer um plano pago. Faça upgrade do seu plano nas configurações de assinatura e tente novamente.
- Name
403 - Forbidden- Description
A moderação de conteúdo bloqueou o prompt ou uma imagem de entrada. Altere a entrada e tente novamente.
- Name
429 - Too Many Requests- Description
Você excedeu seu limite de taxa. Aguarde e tente novamente. Veja Limites de taxa.
Obter uma tarefa de Texto para 3D
Retorna uma tarefa de Texto para 3D pelo seu ID. Funciona tanto para tarefas de preview quanto de refine.
Request
curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"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=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"prompt": "a monster mask",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
Parâmetros
- Name
- id
- Type
- path
- Description
O ID da tarefa a partir da resposta de criação.
Retornos
O objeto de tarefa de Texto para 3D.
Exemplos
A tabela a seguir mostra um modelo de exemplo para cada mode.
| Mode | Modelo de exemplo |
|---|---|
| Preview | ![]() |
| Refine | ![]() |
Excluir uma tarefa de Texto para 3D
Exclui permanentemente uma tarefa de Texto para 3D, incluindo seus modelos e dados. Você não pode desfazer uma exclusão.
Request
curl --request DELETE \
--url https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
// 200 OK on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS. The task keeps running:
{
"message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}
Parâmetros de caminho
- Name
- id
- Type
- path
- Description
O ID da tarefa a ser excluída.
Status da tarefa
Excluir uma tarefa PENDING reembolsa os créditos usados na sua criação.
Uma tarefa IN_PROGRESS não pode ser excluída. A solicitação retorna 409 Conflict,
e a tarefa continua em execução. A Meshy não reembolsa uma tarefa que já foi iniciada,
então excluí-la custaria tanto os créditos quanto o resultado. Aguarde até que ela
alcance o status SUCCEEDED, FAILED ou CANCELED para então excluí-la.
Excluir uma tarefa em um status final (SUCCEEDED, FAILED ou CANCELED)
não reembolsa seus créditos.
Retornos
200 OK quando a tarefa é excluída, ou 409 Conflict quando a tarefa está
IN_PROGRESS.
Listar tarefas de Texto para 3D
Retorna uma lista das suas tarefas de Texto para 3D.
Request
curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response
[
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"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=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***"
},
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"prompt": "a monster mask",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
]
Parâmetros
- Name
- page_num
- Type
- integer
- padrão 1
- Description
O número da página a ser retornada, até
255. Um valor maior retorna400.
- Name
- page_size
- Type
- integer
- padrão 10
- Description
O número de tarefas por página, até
100.
- Name
- sort_by
- Type
- string
- Description
A ordem de classificação.
Valores disponíveis:
+created_at: mais antigas primeiro-created_at: mais recentes primeiro
Retornos
Uma lista paginada de objetos de tarefa de Texto para 3D.
Transmitir uma tarefa de Texto para 3D em stream
Transmite as atualizações de uma tarefa de Texto para 3D como Server-Sent Events (SSE).
Request
curl -N https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"
Response Stream
// Error event example
event: error
data: {
"status_code": 404,
"message": "Task not found"
}
// Message event examples illustrate task progress.
// These examples are shortened. Each event holds the full task object.
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"progress": 0,
"status": "PENDING"
}
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"progress": 50,
"status": "IN_PROGRESS"
}
event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"progress": 100,
"status": "SUCCEEDED",
"created_at": 1692771650657,
"started_at": 1692771667037,
"finished_at": 1692771669037,
"model_urls": {
"glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.glb?Expires=***"
},
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
Parâmetros
- Name
- id
- Type
- path
- Description
O ID da tarefa retornado na resposta de criação.
Retornos
Um stream de objetos de tarefa de Texto para 3D como Server-Sent Events.
Cada evento contém o objeto de tarefa completo, no mesmo formato retornado pelo endpoint Get. Enquanto a tarefa estiver PENDING ou IN_PROGRESS, seus campos de resultado ainda não têm valores.
O objeto de tarefa Texto para 3D
Um objeto de tarefa Texto para 3D descreve uma tarefa que gera um modelo 3D a partir de um prompt de texto. Ele contém o status, o progress e os arquivos do modelo quando a tarefa é concluída com sucesso. Texto para 3D tem dois estágios, preview e refine. Uma tarefa de preview gera um modelo 3D apenas com malha, e uma tarefa de refine gera um modelo 3D texturizado a partir do resultado do preview.
Propriedades
Example Text to 3D Task Object
{
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "text-to-3d-preview",
"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=***",
"usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
"obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?Expires=***",
"mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
"stl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.stl?Expires=***"
},
"prompt": "a monster mask",
"texture_prompt": "green slimy skin with scales and warts",
"texture_image_url": "",
"thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
"progress": 100,
"started_at": 1692771667037,
"created_at": 1692771650657,
"finished_at": 1692771669037,
"status": "SUCCEEDED",
"texture_urls": [
{
"base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***",
"metallic": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_metallic.png?Expires=XXX",
"normal": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_normal.png?Expires=XXX",
"roughness": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_roughness.png?Expires=XXX",
"emission": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0_emission.png?Expires=XXX"
}
],
"preceding_tasks": 0,
"task_error": null,
"consumed_credits": 20
}
- Name
- id
- Type
- string
- Description
O ID da tarefa. Trate-o como uma string opaca e não dependa do seu formato.
- Name
- type
- Type
- string
- Description
O tipo da tarefa,
text-to-3d-previewpara uma tarefa de preview outext-to-3d-refinepara uma tarefa de refine.
- Name
- model_urls
- Type
- object
- Description
URLs de download para o modelo 3D gerado, uma por formato de arquivo. Um formato que a tarefa não gerou não tem chave, em vez de uma string vazia.
- Name
glb- Type
- string
- Description
O arquivo GLB.
- Name
fbx- Type
- string
- Description
O arquivo FBX.
- Name
usdz- Type
- string
- Description
O arquivo USDZ.
- Name
obj- Type
- string
- Description
O arquivo OBJ.
- Name
mtl- Type
- string
- Description
O arquivo MTL.
- Name
stl- Type
- string
- Description
O arquivo STL.
- Name
3mf- Type
- string
- Description
O arquivo 3MF. Presente apenas quando
target_formatsinclui3mf.
- Name
- prompt
- Type
- string
- Description
O
promptque você enviou para criar a tarefa, sem modificações.
- Name
- texture_prompt
- Type
- string
- Description
O prompt de texto que você enviou para guiar a texturização no estágio de refine.
- Name
- ultra_mode
- Type
- boolean
- ⚠ obsoleto
- Description
Use
geometry_resolutionem vez disso.
- Name
- geometry_resolution
- Type
- string
- Description
O nível Ultra em que a tarefa de preview foi executada,
2kou4k. O campo está ausente parastandard.
- Name
- texture_image_url
- Type
- string
- Description
URL de download para a imagem que você enviou para guiar a texturização.
- Name
- thumbnail_url
- Type
- string
- Description
URL de download para uma imagem em miniatura do modelo 3D.
- Name
- alpha_thumbnail_url
- Type
- string
- Description
URL de download para uma versão de
thumbnail_urlcom fundo transparente (RGBA). Presente apenas quando você criou a tarefa comalpha_thumbnail: truee a Meshy renderizou a prévia transparente.
- Name
- progress
- Type
- integer
- Description
Quanto da tarefa foi concluído, em porcentagem. É
0até a tarefa começar e100quando ela é concluída com sucesso.
- Name
- started_at
- Type
- timestamp
- Description
Horário em que a tarefa foi iniciada, em milissegundos Unix. É
0até a tarefa começar.
- Name
- created_at
- Type
- timestamp
- Description
Horário em que a tarefa foi criada, em milissegundos Unix.
- Name
- finished_at
- Type
- timestamp
- Description
Horário em que a tarefa foi finalizada, em milissegundos Unix. É
0até a tarefa ser finalizada.
- Name
- status
- Type
- string
- Description
O status da tarefa, um de
PENDING,IN_PROGRESS,SUCCEEDED,FAILED, ouCANCELED.
- Name
- texture_urls
- Type
- array
- Description
URLs de download para os mapas de textura gerados, como um array de objetos. Geralmente contém um objeto. Cada objeto tem estes campos:
- Name
base_color- Type
- string
- Description
O mapa de cor base.
- Name
metallic- Type
- string
- Description
O mapa metálico. Ausente quando você criou a tarefa com
enable_pbr: false.
- Name
normal- Type
- string
- Description
O mapa de normais. Ausente quando você criou a tarefa com
enable_pbr: false.
- Name
roughness- Type
- string
- Description
O mapa de rugosidade. Ausente quando você criou a tarefa com
enable_pbr: false.
- Name
emission- Type
- string
- Description
O mapa de emissão. Ausente em qualquer um destes casos:
- Você criou a tarefa com
enable_pbr: false. ai_modelémeshy-6-lite,meshy-7,meshy-7.1, oulatest.texture_resolutioné8k.- A tarefa refina um preview
meshy-t2oumeshy-t2.5sem definirai_model.
- Você criou a tarefa com
- Name
- preceding_tasks
- Type
- integer
- Description
O número de tarefas à frente desta na fila. O valor só é significativo enquanto a tarefa está
PENDING.
- Name
- task_error
- Type
- object
- Description
Os detalhes do erro quando a tarefa falha. É
nulla menos que o status sejaFAILED. Veja Erros.
- Name
- consumed_credits
- Type
- integer
- Description
O número de créditos que a tarefa usou. Presente quando o status é
PENDING,IN_PROGRESS, ouSUCCEEDED. É0para uma tarefaFAILED, porque a Meshy reembolsa os créditos quando uma tarefa falha.

