API de Imagem para 3D

Transforme uma imagem num modelo 3D, com ou sem texturas, nos formatos que escolher. Envie a imagem, ou utilize o resultado de uma tarefa de Texto para imagem ou Imagem para imagem.

POST/openapi/v1/image-to-3d

Criar uma tarefa Imagem para 3D

Cria uma tarefa Imagem para 3D. A tarefa é executada em segundo plano. Para saber quanto tempo uma tarefa costuma demorar, consulte Tempos de processamento.

Request

POST

/openapi/v1/image-to-3d

# Simple request with required params
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

# With Ultra 4K geometry, remesh, PBR, and A-pose
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "meshy-7.1",
    "geometry_resolution": "4k",
    "enable_pbr": true,
    "should_remesh": true,
    "target_polycount": 100000,
    "should_texture": true,
    "pose_mode": "a-pose",
    "target_formats": ["glb"]
  }'

# Textured with Meshy N1 from the input image
curl https://api.meshy.ai/openapi/v1/image-to-3d \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "ai_model": "meshy-7.1",
    "texture_model": "meshy-n1"
  }'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Parâmetros

Name
input_task_id
Type
string
Obrigatório
Description
Obrigatório, a menos que envie image_url. O ID de uma tarefa Texto para imagem ou Imagem para imagem cuja imagem pretende usar como entrada. A tarefa tem de ter sido criada por si através da API, ter o estado SUCCEEDED e ter produzido exatamente uma imagem.

Name
image_url
Type
string
Obrigatório
Description
Obrigatório, a menos que envie input_task_id. A imagem a transformar num modelo 3D, como URL público ou como Data URI codificado em base64, por exemplo data:image/jpeg;base64,<os seus dados de imagem codificados em base64>. Se enviar ambos, a Meshy utiliza input_task_id.
A imagem tem de ser um ficheiro JPG, JPEG, PNG ou WebP com, no máximo, 20 MB, pelo menos 32 pixels de cada lado e, no máximo, 178 956 970 pixels (largura × altura).

Name
model_type
Type
string
predefinição standard
Description
O tipo de malha 3D a gerar.
Valores disponíveis:
- standard: uma malha de alto detalhe
- smart-topology: uma malha de um modelo Smart Topology, que escolhe com ai_model (meshy-t2 ou meshy-t2.5)
Com smart-topology, a Meshy ignora should_remesh, save_pre_remeshed_model e decimation_mode, e só aceita topology: triangle.
Name
ai_model
Type
string
predefiniçã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):
- latest: Meshy 7.1
- meshy-7.1
- meshy-6
- meshy-6-lite
- meshy-7 (obsoleto): utilize meshy-7.1 em alternativa
Os modelos Smart Topology (model_type: smart-topology) produzem triângulos, com um número de faces que pode definir com target_polycount:
- meshy-t2: topologia mais limpa e peças separadas de forma nativa
- meshy-t2.5 (predefinição): detalhe mais nítido para assets de jogos
Name
geometry_resolution
Type
string
predefinição standard
Description
A passagem de geração de geometria.
Valores disponíveis:
- standard
- 2k: executa a passagem Ultra a 2048³
- 4k: executa a passagem Ultra a 4096³, para o máximo de detalhe de superfície
2k requer meshy-7.1, latest ou o meshy-7 obsoleto. 4k requer meshy-7.1 ou latest.
Name
ultra_mode
Type
boolean
⚠ obsoleto
predefinição false
Description
Utilize geometry_resolution em alternativa. ultra_mode: true é o mesmo que geometry_resolution: "2k".
Name
should_texture
Type
boolean
predefinição true
Description
Se deve gerar texturas. true devolve um modelo texturizado, e false ignora a texturização e devolve uma malha sem textura.

Aplica-se apenas quando should_texture = true

Name
texture_model
Type
string
predefinição depends on ai_model
Description
O modelo de IA que texturiza o modelo 3D, na mesma tarefa. Deixe de fora para usar o modelo de textura predefinido para o seu ai_model. Não altera o custo em créditos.
Valores disponíveis:
- meshy-7: Meshy 7, com mapas PBR e texturas até 8K
- meshy-n1: Meshy N1, uma textura de cor base 2K apenas a partir de imagens de referência
- meshy-6-lite: Meshy 6 Lite, uma textura 2K ao custo mais baixo
- meshy-6: Meshy 6, apenas como predefinição para ai_model: meshy-6
Todos os ai_model aceitam meshy-7, meshy-n1 e meshy-6-lite. Uma opção que o modelo de textura escolhido não suporta devolve 400. Com meshy-n1, um modelo gerado com mais de 7 999 999 triângulos faz a tarefa falhar, e a Meshy reembolsa os créditos. Com should_texture: false, a Meshy ignora texture_model, mas um valor desconhecido continua a devolver 400.
Consulte Modelos para saber o que cada modelo de textura faz e qual escolher.
Name
enable_pbr
Type
boolean
predefinição false
Description
Se deve também gerar mapas PBR (metallic, roughness e normal) além da cor base. true requer should_texture: true, e devolve 400 com should_texture: false. Com texture_model: meshy-n1, true devolve 400.
O modelo de textura Meshy 6 também gera um mapa de emissão, exceto com texture_resolution: 8k.
Name
texture_resolution
Type
string
predefinição 2k
Description
O tamanho da textura de cor base. Uma textura maior capta mais detalhe de superfície.
Valores disponíveis:
- 2k: 2048×2048
- 4k: 4096×4096
- 8k: 8192×8192
4k e 8k requerem o modelo de textura Meshy 7 ou Meshy 6, e devolvem 400 com os outros. A 8k, a Meshy não produz um mapa de emissão.
Name
hd_texture
Type
boolean
⚠ obsoleto
predefinição false
Description
Utilize texture_resolution em alternativa. hd_texture: true é o mesmo que texture_resolution: "4k". Se enviar ambos, a Meshy utiliza texture_resolution.
Name
texture_prompt
Type
string
Description
Texto que orienta a textura, até 800 carateres. Um texto mais longo devolve 400. Com texture_model: meshy-n1, enviá-lo devolve 400.
Name
texture_image_url
Type
string
Description
Uma imagem que orienta a textura, como URL público ou como Data URI codificado em base64, por exemplo data:image/jpeg;base64,<os seus dados de imagem codificados em base64>. A imagem tem de ser um ficheiro JPG, JPEG, PNG ou WebP com, no máximo, 20 MB, pelo menos 32 pixels de cada lado e, no máximo, 178 956 970 pixels (largura × altura).
A Meshy orienta a textura apenas com um de texture_prompt e texture_image_url. Se enviar ambos, a Meshy utiliza texture_prompt. Para o custo em créditos da texturização, consulte Preços.
Com texture_model: meshy-n1, a Meshy texturiza a partir desta imagem como a vista frontal, ou a partir da imagem de entrada quando a deixa de fora.
Texturizar a partir de uma imagem pode não funcionar bem quando a forma da imagem difere muito da geometria do modelo 3D.

Name
should_remesh
Type
boolean
predefinição true (meshy-6-lite), false (other models)
Description
Se deve executar a fase de remesh. Para o modelo 3D de maior qualidade, defina como false.

Aplica-se apenas quando should_remesh = true

Name
topology
Type
string
predefinição triangle
Description
O tipo de face do modelo com remesh.
Valores disponíveis:
- quad: uma malha predominantemente de quadriláteros
- triangle: uma malha de triângulos decimada
O resultado do Smart Topology é apenas de triângulos, pelo que quad com meshy-t2 ou meshy-t2.5 devolve 400. Com texture_model: meshy-n1, quad devolve 400 quando o modelo tem remesh, o que meshy-6-lite faz por predefinição.
Name
decimation_mode
Type
integer
Description
Número de faces adaptativo, por nível. Quando o define, a Meshy ignora target_polycount.
Valores disponíveis:
- 1: ultra
- 2: alto
- 3: médio
- 4: baixo
Name
save_pre_remeshed_model
Type
boolean
predefinição false
Description
Se deve também guardar um GLB do modelo antes da fase de remesh. A Meshy devolve-o em model_urls.pre_remeshed_glb.

Name
target_polycount
Type
integer
Description
O número de faces a atingir. O resultado pode diferir do valor-alvo, dependendo da geometria do modelo.
Aplica-se em dois casos distintos:
- Remesh: Quando should_remesh é true num modelo standard, a Meshy decima a malha para cerca deste número. Se definir decimation_mode, a Meshy usa-o e ignora target_polycount.
- Smart Topology: Quando model_type é smart-topology e ai_model é meshy-t2 ou meshy-t2.5, a Meshy gera o modelo com este número de faces. Não é executado nenhum remesh, e não precisa de should_remesh.
O intervalo e a predefinição dependem do caso:
Caso Intervalo Predefinição
Remesh 100 a 300000 30000
meshy-t2 100 a 15000 4000
meshy-t2.5 100 a 30000 15000
Um valor fora do intervalo devolve 400.

Caso	Intervalo	Predefinição
Remesh	`100` a `300000`	`30000`
`meshy-t2`	`100` a `15000`	`4000`
`meshy-t2.5`	`100` a `30000`	`15000`

Name
symmetry_mode
Type
string
⚠ obsoleto
predefinição auto
Description
Deixe de fora, porque não afeta o resultado. Os seus valores controlavam a simetria durante a geração:
- off: sem simetria
- auto: simetria escolhida a partir da geometria de entrada
- on: simetria forçada
Name
pose_mode
Type
string
predefinição ""
Description
A pose para o modelo gerado.
Valores disponíveis:
- a-pose: uma pose A
- t-pose: uma pose T
- "" (cadeia vazia): sem pose específica
Name
is_a_t_pose
Type
boolean
⚠ obsoleto
predefinição false
Description
Utilize pose_mode em alternativa. Se deve gerar o modelo numa pose A ou T.
Name
surface_mode
Type
string
⚠ obsoleto
Description
Utilize ai_model em alternativa. Não afeta o resultado, porque a geração de modelo que selecionava foi descontinuada.
Os valores aceites são organic e hard. Qualquer outro valor devolve 400.
Name
image_enhancement
Type
boolean
predefinição true
Description
Se deve otimizar a imagem de entrada antes de gerar. false mantém o aspeto exato da imagem de entrada, sem qualquer processamento de estilo.
Só funciona com meshy-6, meshy-7.1 ou latest. Com meshy-6-lite ou model_type: smart-topology, devolve 400.
Name
remove_lighting
Type
boolean
predefinição true
Description
Se deve remover realces e sombras da textura de cor base. O resultado fica mais limpo e funciona melhor com a sua própria iluminação.
Só tem efeito com o modelo de textura Meshy 6, e um modelo de textura que não o suporte devolve 400 para true. Com model_type: smart-topology, ou com ai_model: meshy-6-lite e o respetivo modelo de textura predefinido, enviá-lo devolve 400.
Name
moderation
Type
boolean
predefinição false
Description
Se deve analisar estas entradas em busca de conteúdo nocivo antes de gerar:
- image_url
- texture_image_url
- texture_prompt
Se a Meshy detetar conteúdo nocivo, o pedido devolve 400 e a Meshy não cria a tarefa.
Name
target_formats
Type
string[]
Description
Os formatos de ficheiro a gerar. A Meshy gera e devolve apenas os formatos que listar, o que pode encurtar a tarefa. Se o deixar de fora, a Meshy gera todos os formatos exceto 3mf, que só obtém se o listar.
Valores disponíveis:
- glb
- obj
- fbx
- stl
- usdz
- 3mf
Name
auto_size
Type
boolean
predefinição false
Description
Se deve estimar a altura real do objeto com visão por IA e redimensionar o modelo em conformidade. A Meshy coloca a origem na base, a menos que defina origin_at.
Name
alpha_thumbnail
Type
boolean
predefinição false
Description
Se deve também gerar uma pré-visualização com fundo transparente (RGBA), devolvida em alpha_thumbnail_url quando obtém a tarefa. thumbnail_url não é alterado.
Name
multi_view_thumbnails
Type
boolean
predefinição false
Description
Se deve também gerar pré-visualizações de frente, direita, trás e esquerda, devolvidas em thumbnail_urls quando obtém a tarefa. thumbnail_url não é alterado e continua a mostrar a vista frontal. Isto acrescenta cerca de 5 segundos à tarefa.

Aplica-se apenas quando auto_size = true

Name
origin_at
Type
string
predefinição bottom
Description
Onde colocar a origem do modelo, bottom ou center.

Retorno

O campo result da resposta contém o ID da nova tarefa Imagem para 3D.

Modos de falha

Name
400 - Bad Request
Description
O pedido não pode ser executado. A mensagem de erro indica qual o problema encontrado. Por exemplo:
- Parâmetro em falta: Nem image_url nem input_task_id foram enviados.
- Tarefa de entrada inválida: input_task_id não é uma tarefa Texto para imagem ou Imagem para imagem com estado SUCCEEDED que tenha produzido exatamente uma imagem.
- Formato de imagem inválido: A imagem de image_url não é um ficheiro JPG, JPEG, PNG ou WebP.
- URL inacessível: A Meshy não consegue transferir a imagem de image_url, porque o URL devolve 404 ou expira.
- Imagem demasiado grande: A imagem de image_url ou texture_image_url tem mais de 20 MB.
- Tamanho de imagem inválido: A imagem de image_url ou texture_image_url tem um lado com menos de 32 pixels, ou mais de 178 956 970 pixels (largura × altura).
- Data URI inválido: A cadeia base64 está mal formada.
- Combinação de parâmetros inválida: enable_pbr é true, e should_texture é false.
- Modelo não suportado para Ultra: geometry_resolution é 2k ou 4k, com um ai_model que não o consegue executar.
- Modelo não suportado para opções de imagem: um dos seguintes:
  - image_enhancement foi enviado com ai_model: "meshy-6-lite" ou model_type: "smart-topology".
  - remove_lighting foi enviado com model_type: "smart-topology", ou com ai_model: "meshy-6-lite" e o respetivo modelo de textura predefinido.
- Modelo de textura inválido: texture_model não é um dos valores disponíveis.
- Modelo de textura não disponível: texture_model é meshy-6 com um ai_model diferente de meshy-6. Envie meshy-7, meshy-n1 ou meshy-6-lite, ou deixe de fora.
- Opção não suportada para o modelo de textura: O pedido solicita ao modelo de textura uma opção que este não suporta, como enable_pbr: true com meshy-n1 ou uma textura 4k com meshy-6-lite. Consulte Modelos.
Corrija o pedido e envie-o novamente. Consulte Erros.
Name
401 - Unauthorized
Description
A chave de API está em falta 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 o seu saldo de créditos e tente novamente.
- Plano gratuito: Criar uma tarefa requer um plano pago. Atualize o seu plano nas definições de subscrição 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
404 - Not Found
Description
input_task_id não corresponde a nenhuma das suas tarefas. Verifique o ID da tarefa e envie o pedido novamente.
Name
429 - Too Many Requests
Description
Excedeu o seu limite de taxa. Aguarde e tente novamente. Consulte Limites de taxa.

GET/openapi/v1/image-to-3d/:id

Obter uma tarefa de Imagem para 3D

Devolve uma tarefa de Imagem para 3D através do seu ID.

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl https://api.meshy.ai/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "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=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "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": 30
}

Parâmetros

Name
id
Type
path
Description
O ID da tarefa proveniente da resposta de criação.

Retorna

O objeto de tarefa de Imagem para 3D.

DELETE/openapi/v1/image-to-3d/:id

Eliminar uma tarefa de Imagem para 3D

Elimina permanentemente uma tarefa de Imagem para 3D, incluindo os seus modelos e dados. Não pode anular uma eliminação.

Request

DELETE

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/image-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 eliminar.

Estado da tarefa

Eliminar uma tarefa PENDING reembolsa os créditos utilizados quando a criou.

Uma tarefa IN_PROGRESS não pode ser eliminada. O pedido devolve 409 Conflict, e a tarefa continua em execução. A Meshy não reembolsa uma tarefa que já começou, pelo que eliminá-la custar-lhe-ia tanto os créditos como o resultado. Aguarde que atinja o estado SUCCEEDED, FAILED ou CANCELED, e depois elimine-a.

Eliminar uma tarefa num estado final (SUCCEEDED, FAILED ou CANCELED) não reembolsa os seus créditos.

Devolve

200 OK quando a tarefa é eliminada, ou 409 Conflict quando a tarefa está IN_PROGRESS.

GET/openapi/v1/image-to-3d

Listar tarefas de Imagem para 3D

Devolve uma lista das suas tarefas de Imagem para 3D.

Request

GET

/openapi/v1/image-to-3d

curl https://api.meshy.ai/openapi/v1/image-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "image-to-3d",
    "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=***",
      "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?Expires=***",
      "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
    },
    "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
    "thumbnail_urls": {
      "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
      "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
      "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
      "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
    },
    "texture_prompt": "",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "expires_at": 1692771679037,
    "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": 30
  }
]

Parâmetros

Name
page_num
Type
integer
predefinição 1
Description
O número de página a devolver, até 255. Um valor superior devolve 400.
Name
page_size
Type
integer
predefinição 10
Description
O número de tarefas por página, até 100.
Name
sort_by
Type
string
Description
A ordem de ordenação.
Valores disponíveis:
- +created_at: mais antigas primeiro
- -created_at: mais recentes primeiro

Devolve

Uma lista paginada de objetos de tarefa de Imagem para 3D.

GET/openapi/v1/image-to-3d/:id/stream

Transmitir uma tarefa de Imagem para 3D

Transmite as atualizações de uma tarefa de Imagem para 3D como Server-Sent Events (SSE).

Request

GET

/openapi/v1/image-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream

curl -N https://api.meshy.ai/openapi/v1/image-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",
  "type": "image-to-3d",
  "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=***",
  "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=***",
  "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "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": 30
}

Parâmetros

Name
id
Type
path
Description
O ID da tarefa proveniente da resposta de criação.

Devolve

Um stream de objetos de tarefa de Imagem para 3D como Server-Sent Events.

Cada evento contém o objeto de tarefa completo, na mesma estrutura devolvida pelo endpoint Get. Enquanto a tarefa estiver PENDING ou IN_PROGRESS, os campos de resultado ainda não têm valores.

O objeto de tarefa Imagem para 3D

Um objeto de tarefa Imagem para 3D descreve uma geração de um modelo 3D a partir de uma imagem. Contém o estado, o progress e os ficheiros do modelo quando a tarefa é bem-sucedida.

Propriedades

Example Image to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "image-to-3d",
  "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=***",
    "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=***",
    "pre_remeshed_glb": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/pre_remeshed_model.glb?Expires=***"
  },
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "thumbnail_urls": {
    "front": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_front.png?Expires=***",
    "right": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_right.png?Expires=***",
    "back": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_back.png?Expires=***",
    "left": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview_left.png?Expires=***"
  },
  "texture_prompt": "",
  "texture_image_url": "",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "expires_at": 1692771679037,
  "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": 30
}

Name
id
Type
string
Description
O ID da tarefa. Trate-o como uma cadeia opaca e não dependa do seu formato.
Name
type
Type
string
Description
O tipo de tarefa, sempre image-to-3d.
Name
model_urls
Type
object
Description
URLs de transferência para o modelo 3D gerado, uma por formato de ficheiro. Um formato que a tarefa não gerou não tem chave, em vez de uma string vazia.
- Name
  glb
  Type
  string
  Description
  O ficheiro GLB.
- Name
  fbx
  Type
  string
  Description
  O ficheiro FBX.
- Name
  obj
  Type
  string
  Description
  O ficheiro OBJ.
- Name
  usdz
  Type
  string
  Description
  O ficheiro USDZ.
- Name
  mtl
  Type
  string
  Description
  O ficheiro MTL, devolvido com um ficheiro OBJ quando o modelo tem texturas.
- Name
  stl
  Type
  string
  Description
  O ficheiro STL.
- Name
  3mf
  Type
  string
  Description
  O ficheiro 3MF. Presente apenas quando target_formats inclui 3mf.
- Name
  pre_remeshed_glb
  Type
  string
  Description
  O ficheiro GLB anterior ao remesh. Presente apenas quando criou a tarefa com should_remesh: true e save_pre_remeshed_model: true.
Name
thumbnail_url
Type
string
Description
URL de transferência para uma imagem de pré-visualização do modelo 3D. Quando thumbnail_urls está presente, é a mesma imagem que thumbnail_urls.front. A Meshy mantém-no para compatibilidade retroativa.
Name
alpha_thumbnail_url
Type
string
Description
URL de transferência para uma versão de thumbnail_url com fundo transparente (RGBA). Presente apenas quando criou a tarefa com alpha_thumbnail: true e a Meshy renderizou a pré-visualização transparente.
Name
thumbnail_urls
Type
object
Description
URLs de transferência para pré-visualizações do modelo 3D a partir de quatro lados. Cada valor é um URL assinado para um PNG de 512×512, renderizado com os mesmos materiais e iluminação que thumbnail_url. Utilize-os para pré-visualizar o modelo a partir de vários ângulos, por exemplo num pipeline em lote, sem transferir o GLB.
Presente apenas quando criou a tarefa com multi_view_thumbnails: true e a tarefa atingiu SUCCEEDED. As tarefas criadas sem multi_view_thumbnails: true não incluem este campo.
- Name
  front
  Type
  string
  Description
  A vista frontal, a 0° em torno do eixo vertical. Corresponde a thumbnail_url.
- Name
  right
  Type
  string
  Description
  A vista direita, a 90°.
- Name
  back
  Type
  string
  Description
  A vista traseira, a 180°.
- Name
  left
  Type
  string
  Description
  A vista esquerda, a 270°.
Name
texture_prompt
Type
string
Description
O prompt de texto que orientou a textura.
Name
texture_image_url
Type
string
Description
URL de transferência para a imagem que orientou a textura.
Name
ultra_mode
Type
boolean
⚠ obsoleto
Description
Consulte antes geometry_resolution.
Name
geometry_resolution
Type
string
Description
O nível Ultra em que a tarefa foi executada, 2k ou 4k. Uma tarefa standard não inclui este campo.
Name
progress
Type
integer
Description
Quanto da tarefa está concluído, em percentagem. É 0 até a tarefa começar e 100 quando é bem-sucedida.
Name
started_at
Type
timestamp
Description
Hora em que a tarefa começou, em milissegundos Unix. É 0 até a tarefa começar.
Name
created_at
Type
timestamp
Description
Hora em que a tarefa foi criada, em milissegundos Unix.
Name
expires_at
Type
timestamp
Description
Hora em que o resultado da tarefa expira, em milissegundos Unix.
Name
finished_at
Type
timestamp
Description
Hora em que a tarefa terminou, em milissegundos Unix. É 0 até a tarefa terminar.
Name
status
Type
string
Description
O estado da tarefa, um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED ou CANCELED.
Name
texture_urls
Type
array
Description
Os mapas de textura que a tarefa gerou, como um array de objetos. Normalmente contém um objeto, com estes campos:
- Name
  base_color
  Type
  string
  Description
  URL de transferência para o mapa de cor base.
- Name
  metallic
  Type
  string
  Description
  URL de transferência para o mapa metálico. O campo está ausente quando criou a tarefa com enable_pbr: false.
- Name
  normal
  Type
  string
  Description
  URL de transferência para o mapa de normais. O campo está ausente quando criou a tarefa com enable_pbr: false.
- Name
  roughness
  Type
  string
  Description
  URL de transferência para o mapa de rugosidade. O campo está ausente quando criou a tarefa com enable_pbr: false.
- Name
  emission
  Type
  string
  Description
  URL de transferência para o mapa de emissão. A Meshy inclui-o apenas quando criou a tarefa com todos estes:
  
  ai_model: meshy-6, com o seu modelo de textura predefinido
  
  enable_pbr: true
  
  um texture_resolution de 2k ou 4k
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. É null a menos que o estado seja FAILED. Consulte Erros.
Name
consumed_credits
Type
integer
Description
O número de créditos que a tarefa utilizou. Presente quando o estado é PENDING, IN_PROGRESS ou SUCCEEDED. É 0 para uma tarefa FAILED, porque a Meshy reembolsa os créditos quando uma tarefa falha.