Retexture API é uma funcionalidade que permite integrar as capacidades de retexturização por IA do Meshy na sua própria aplicação. Nesta secção, encontrará todas as informações
de que precisa para começar a usar esta API.
Este endpoint permite-lhe criar uma nova tarefa de Retexturização. Consulte
O Objeto Tarefa de Retexturização para ver que
propriedades estão incluídas no objeto tarefa de Retexturização.
Parâmetros
Apenas um de input_task_id ou model_url é obrigatório. Se ambos forem fornecidos, input_task_id tem prioridade.
Name
input_task_id
Type
string
Obrigatório
Description
O ID da tarefa concluída de Imagem para 3D ou Texto para 3D que deseja retexturizar.
Esta tarefa deve ser uma das seguintes tarefas: Texto para 3D Prévia, Texto para 3D Refinar, Imagem para 3D ou Remesh. Além disso, deve ter um status de SUCCEEDED.
Name
model_url
Type
string
Obrigatório
Description
Forneça um modelo 3D para o Meshy texturizar. Formatos suportados: .glb, .gltf, .obj, .fbx, .stl.
Existem duas maneiras de fornecer o modelo:
URL acessível publicamente: Um URL acessível a partir da internet pública.
Data URI: Um Data URI codificado em base64 do modelo. Use o tipo MIME application/octet-stream. Exemplo: data:application/octet-stream;base64,<os seus dados de modelo codificados em base64>.
Exatamente um input de estilo é obrigatório: text_style_prompt, image_style_url, ou multiview_image_urls. multiview_image_urls não pode ser combinado com nenhum dos outros dois; se ambos text_style_prompt e image_style_url forem fornecidos, image_style_url tem prioridade.
Name
text_style_prompt
Type
string
Obrigatório
Description
Descreva o estilo desejado da textura do objeto usando texto. Máximo de 600 caracteres.
Name
image_style_url
Type
string
Obrigatório
Description
Forneça uma imagem 2D para guiar o processo de texturização. Atualmente suportamos os formatos .jpg, .jpeg, e .png.
Existem duas maneiras de fornecer a imagem:
URL acessível publicamente: Um URL acessível a partir da internet pública
Data URI: Um Data URI codificado em base64 da imagem. Exemplo de um Data URI: data:image/jpeg;base64,<os seus dados de imagem codificados em base64>
A texturização de imagens pode não funcionar de forma ideal se houver diferenças substanciais de geometria entre o asset original e a imagem carregada.
Name
multiview_image_urls
Type
string[]
Obrigatório
Description
Forneça de 1 a 4 imagens mostrando o mesmo objeto de diferentes vistas para guiar a texturização. A primeira imagem é a vista principal (frontal); a ordem das vistas restantes (esquerda, traseira, direita) não é relevante.
Cada elemento aceita os mesmos formatos que image_style_url (um URL acessível publicamente ou um Data URI base64, .jpg/.jpeg/.png).
Requer ai_model: "meshy-7" (ou latest).
Name
ai_model
Type
string
predefinição latest
Description
ID do modelo de IA a utilizar para a retexturização. Valores disponíveis: meshy-5, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
predefinição false
Description
Mantenha a disposição UV existente do modelo em vez de gerar uma nova.
Se estiver a retexturizar um modelo que o Meshy gerou (via input_task_id, ou um model_url que aponta para um output do Meshy), defina isto como true para reutilizar sua disposição UV otimizada.
Se estiver a retexturizar um modelo de terceiros que carregou, defina true quando este já tiver boas Uvs que deseja manter, ou deixe false para permitir que o Meshy desenrole novas Uvs (melhor para modelos que não têm mapeamento UV adequado).
Name
enable_pbr
Type
boolean
predefinição false
Description
Gere Mapas PBR (metálico, rugosidade, normais) além da cor base. Um mapa de emissão também é incluído quando ai_model é meshy-6, exceto na texture_resolution: 8k. meshy-7 e latest não produzem um mapa de emissão.
Name
texture_resolution
Type
string
predefinição 2k
Description
Resolução da textura da cor base. Um de 2k (2048×2048), 4k (4096×4096), ou 8k (8192×8192). Resoluções mais altas capturam mais detalhes de superfície.
4k e 8k requerem ai_modelmeshy-6, meshy-7 ou latest. Na 8k, nenhum mapa de emissão é produzido.
Name
hd_texture
Type
boolean
⚠ obsoleto
predefinição false
Description
Use texture_resolution em vez disso — equivalente a texture_resolution: "4k". Quando ambos são configurados, texture_resolution tem precedência.
Name
remove_lighting
Type
boolean
predefinição true
Description
Remove destaques e sombras da textura da cor base, produzindo um resultado mais limpo que funciona melhor sob configurações de iluminação personalizadas.
Só suportado quando ai_model é meshy-6.
Name
target_formats
Type
string[]
Description
Especifica quais formatos de arquivo 3D incluir na saída. Apenas os formatos solicitados serão gerados e retornados, o que pode reduzir o tempo de conclusão da tarefa. Quando omitido, todos os formatos suportados são incluídos.
Quando omitido, todos os formatos exceto 3mf são gerados. 3mf só é incluído quando explicitamente especificado.
Name
alpha_thumbnail
Type
boolean
predefinição false
Description
Quando configurado como true, a tarefa renderiza adicionalmente uma versão com fundo transparente (RGBA) da pré-visualização e retorna-a como alpha_thumbnail_url na resposta GET. O campo existente thumbnail_url não é alterado.
Retornos
A propriedade result da resposta contém o id da tarefa de Retexturização recém-criada.
Modos de Falha
Name
400 - Bad Request
Description
A solicitação não foi aceitável. Causas comuns:
Parâmetro ausente: Ou model_url ou input_task_id deve ser fornecido.
Estilo ausente: Um de text_style_prompt, image_style_url ou multiview_image_urls deve ser fornecido.
Entradas de estilo conflitantes: multiview_image_urls não pode ser combinado com text_style_prompt ou image_style_url.
Modelo não suportado para multiview: multiview_image_urls requer ai_model: "meshy-7" (ou latest).
Modelo não disponível: ai_model: "meshy-7" está sendo lançado progressivamente e ainda não está ativado para sua conta.
Tarefa de entrada inválida: O input_task_id deve referir-se a uma tarefa bem-sucedida de um modelo suportado.
Formato de modelo inválido: O model_url aponta para um arquivo com uma extensão não suportada.
URL inacessível: O elemento model_url, image_style_url ou multiview_image_urls não pôde ser descarregado.
Name
401 - Unauthorized
Description
A autenticação falhou. Verifique a sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarefa.
Name
429 - Too Many Requests
Description
Excedeu o seu limite de taxa.
Solicitação
POST
/openapi/v1/retexture
# Retexturização com prompt de textocurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "text_style_prompt": "presas vermelhas, traje de samurai que se funde com o estilo batik japonês", "enable_original_uv": true, "enable_pbr": true }'# Retexturização com estilo de imagem e PBRcurlhttps://api.meshy.ai/openapi/v1/retexture \-H"Authorization: Bearer ${YOUR_API_KEY}" \-H'Content-Type: application/json' \-d'{ "model_url": "https://cdn.meshy.ai/model/example_model_2.glb", "image_style_url": "https://cdn.meshy.ai/image/example_image.jpg", "ai_model": "latest", "enable_pbr": true, "enable_original_uv": true }'
Este endpoint permite-lhe obter uma tarefa de Retexturização dado um id de tarefa válido.
Consulte O Objeto Tarefa de Retexturização para ver que
propriedades estão incluídas no objeto tarefa de Retexturização.
Parâmetros
Name
id
Type
path
Description
Identificador único para a tarefa de Retexturização a ser obtida.
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","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=***","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=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"presas vermelhas, traje de samurai que se funde com o estilo batik japonês","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" } ],"task_error": {"message":"" },"consumed_credits":10}
[ {"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","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=***" },"thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","text_style_prompt":"presas vermelhas, traje de samurai que se funde com o estilo batik japonês","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": {"message":"" },"consumed_credits":10 }]
// Exemplo de evento de erroevent: errordata: {"status_code": 404,"message": "Tarefa não encontrada"}// Exemplos de eventos de mensagem ilustram o progresso da tarefa.// Para tarefas PENDING ou IN_PROGRESS, o fluxo de resposta não incluirá todos os campos.event: messagedata: {"id": "018a210d-8ba4-705c-b111-1f1776f7f578","progress": 0,"status": "PENDING"}event: messagedata: {"id": "018a210d-8ba4-705c-b111-1f1776f7f578","progress": 50,"status": "IN_PROGRESS"}event: messagedata: {"id": "018a210d-8ba4-705c-b111-1f1776f7f578","type": "retexture","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=***","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=***","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=***" },"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": {"message":"" },"consumed_credits": 10}
O objeto Tarefa de Retexturização é uma unidade de trabalho que o Meshy usa para gerar uma textura 3D a partir de inputs de texto ou imagem.
O modelo tem as seguintes propriedades:
Propriedades
Name
id
Type
string
Description
Identificador único para a tarefa. Embora usemos um UUID k-sortable para os IDs de tarefas como detalhe de implementação, não deve fazer suposições sobre o formato do ID.
Name
type
Type
string
Description
Tipo da tarefa de Retexturização. O valor é retexture.
Name
model_urls
Type
object
Description
URL disponível para download do arquivo de modelo 3D texturizado gerado pelo Meshy.
Name
glb
Type
string
Description
URL disponível para download do arquivo GLB.
Name
fbx
Type
string
Description
URL disponível para download do arquivo FBX.
Name
obj
Type
string
Description
URL disponível para download do arquivo OBJ.
Name
usdz
Type
string
Description
URL disponível para download do arquivo USDZ.
Name
mtl
Type
string
Description
URL disponível para download do arquivo MTL, retornado junto com as exportações OBJ quando as texturas estão presentes.
Name
stl
Type
string
Description
URL disponível para download do arquivo STL.
Name
3mf
Type
string
Description
URL disponível para download do arquivo 3MF. Só está presente quando 3mf foi solicitado via target_formats.
Name
text_style_prompt
Type
string
Description
Este é o prompt de texto usado para criar a tarefa de texturização.
Name
image_style_url
Type
string
Description
Este é o input de imagem usado para criar a tarefa de texturização.
Name
multiview_image_urls
Type
string[]
Description
URLs disponíveis para download das imagens de referência de multivista usadas para criar a tarefa de texturização. Só está presente quando a tarefa foi criada com multiview_image_urls.
Name
thumbnail_url
Type
string
Description
URL disponível para download da imagem em miniatura do arquivo do modelo.
Name
alpha_thumbnail_url
Type
string
Description
URL disponível para download de uma versão com fundo transparente (RGBA) de thumbnail_url. Só está presente quando a tarefa foi criada com alpha_thumbnail: true e a pré-visualização transparente foi renderizada com sucesso; caso contrário, este campo é omitido.
Name
progress
Type
integer
Description
Progresso da tarefa. Se a tarefa ainda não começou, esta propriedade será 0. Assim que a tarefa for concluída, isto se tornará 100.
Name
started_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi iniciada, em milissegundos. Se a tarefa ainda não começou, esta propriedade será 0.
Um carimbo de data/hora representa o número de milissegundos decorridos desde 1 de janeiro de 1970 UTC, seguindo
o padrão RFC 3339.
Por exemplo, sexta-feira, 1 de setembro de 2023 às 12:00:00 GMT é representado como 1693569600000. Isto aplica-se
a todos os carimbos de data/hora na Meshy API.
Name
created_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi criada, em milissegundos.
Name
expires_at
Type
timestamp
Description
Carimbo de data/hora de quando o resultado da tarefa expira, em milissegundos.
Name
finished_at
Type
timestamp
Description
Carimbo de data/hora de quando a tarefa foi concluída, em milissegundos. Se a tarefa ainda não foi concluída, esta propriedade será 0.
Name
status
Type
string
Description
Status da tarefa. Os valores possíveis são um de PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
texture_urls
Type
array
Description
Uma matriz de objetos de URL de textura que são gerados a partir da tarefa. Normalmente, isto contém apenas um objeto de URL de textura. Cada URL de textura tem as seguintes propriedades:
Name
base_color
Type
string
Description
URL disponível para download da imagem do mapa de cor base.
Name
metallic
Type
string
Description
URL disponível para download da imagem do mapa metálico.
Se a tarefa for criada com enable_pbr: false, esta propriedade será omitida.
Name
normal
Type
string
Description
URL disponível para download da imagem do mapa de normais.
Se a tarefa for criada com enable_pbr: false, esta propriedade será omitida.
Name
roughness
Type
string
Description
URL disponível para download da imagem do mapa de rugosidade.
Se a tarefa for criada com enable_pbr: false, esta propriedade será omitida.
Name
emission
Type
string
Description
URL disponível para download da imagem do mapa de emissão.
Se a tarefa for criada com enable_pbr: false, ou ai_model for meshy-5, esta propriedade será omitida.
Name
preceding_tasks
Type
integer
Description
A contagem de tarefas precedentes.
Esta propriedade só está presente quando o status da tarefa é PENDING.
Name
task_error
Type
object
Description
Detalhes do erro para tarefas falhadas. Veja Erros para a referência completa do objeto task_error.
Name
consumed_credits
Type
integer
Description
O número de créditos consumidos por esta tarefa. Presente quando o status da tarefa é PENDING, IN_PROGRESS, ou SUCCEEDED. Retorna 0 para tarefas FAILED (os créditos são reembolsados em caso de falha).
Example Retexture Task Model
{"id":"018a210d-8ba4-705c-b111-1f1776f7f578","type":"retexture","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=***" },"text_style_prompt":"presas vermelhas, traje de samurai que se funde com o estilo batik japonês","image_style_url":"https://assets.meshy.ai/***/image/example_image.jpg?Expires=***","thumbnail_url":"https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***","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": {"message":"" },"consumed_credits":10}