A Retexture API é um recurso que permite integrar as capacidades de retexturização por IA da Meshy à sua própria aplicação. Nesta seção, você encontrará todas as informações
necessárias para começar a usar essa API.
Este endpoint permite que você crie uma nova tarefa de Retexturizar. Consulte
O Objeto de Tarefa de Retexturizar para ver quais
propriedades estão incluídas no objeto de tarefa de Retexturizar.
Parâmetros
Apenas um dos parâmetros 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 você deseja retexturizar.
Essa tarefa deve ser uma das seguintes: Texto para 3D Preview, Texto para 3D Refine, Imagem para 3D ou Remesh. Além disso, ela deve ter o status 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.
Há duas maneiras de fornecer o modelo:
URL publicamente acessível: uma URL que é acessível pela internet pública.
Data URI: um data URI do modelo codificado em base64. Use o MIME type application/octet-stream. Exemplo: data:application/octet-stream;base64,<seus dados de modelo codificados em base64>.
Exatamente uma entrada de estilo é obrigatória: text_style_prompt, image_style_url ou multiview_image_urls. multiview_image_urls não pode ser combinado com nenhum dos outros dois; se tanto text_style_prompt quanto image_style_url forem fornecidos, image_style_url tem prioridade.
Name
text_style_prompt
Type
string
Obrigatório
Description
Descreva o estilo de textura desejado para o objeto usando texto. Máximo de 800 caracteres.
Name
image_style_url
Type
string
Obrigatório
Description
Forneça uma imagem 2D para guiar o processo de texturização. Atualmente, oferecemos suporte aos formatos .jpg, .jpeg e .png.
Há duas maneiras de fornecer a imagem:
URL publicamente acessível: uma URL que é acessível pela internet pública
Data URI: um data URI da imagem codificado em base64. Exemplo de data URI: data:image/jpeg;base64,<seus dados de imagem codificados em base64>
A texturização por imagem pode não funcionar de forma ideal se houver diferenças significativas de geometria entre o asset original e a imagem enviada.
Name
multiview_image_urls
Type
string[]
Obrigatório
Description
Forneça de 1 a 4 imagens mostrando o mesmo objeto a partir de diferentes ângulos para guiar a texturização. A primeira imagem é a vista principal (frontal); a ordem das demais vistas (esquerda, traseira, direita) não importa.
Cada elemento aceita os mesmos formatos que image_style_url (uma URL publicamente acessível ou um data URI em base64, .jpg/.jpeg/.png).
Requer explicitamente ai_model: "meshy-7".
Name
ai_model
Type
string
padrão latest
Description
ID do modelo de IA a ser usado para a retexturização. Valores disponíveis: meshy-6-lite, meshy-6, meshy-7, latest (Meshy 7).
Name
enable_original_uv
Type
boolean
padrão false
Description
Mantém o layout UV existente do modelo em vez de gerar um novo.
Se você está retexturizando um modelo que o Meshy gerou (via input_task_id, ou um model_url que aponta para uma saída do Meshy), defina isso como true para reutilizar seu layout UV otimizado.
Se você está retexturizando um modelo de terceiros que enviou, defina como true quando ele já tiver bons UVs que você deseja manter, ou deixe como false para que o Meshy desdobre UVs novos (melhor para modelos que não possuem um mapeamento UV adequado).
Name
enable_pbr
Type
boolean
padrão false
Description
Gera mapas PBR (metálico, rugosidade, normal) além da cor base. Um mapa de emissão também é incluído quando ai_model é meshy-6, exceto em texture_resolution: 8k. meshy-6-lite, meshy-7 e latest não produzem um mapa de emissão.
Name
texture_resolution
Type
string
padrão 2k
Description
Resolução da textura de cor base. Uma entre 2k (2048×2048), 4k (4096×4096) ou 8k (8192×8192). Resoluções mais altas capturam mais detalhes da superfície.
4k e 8k exigem ai_modelmeshy-6, meshy-7 ou latest. Em 8k, nenhum mapa de emissão é produzido.
Name
hd_texture
Type
boolean
⚠ obsoleto
padrão false
Description
Use texture_resolution em vez disso — equivalente a texture_resolution: "4k". Quando ambos são definidos, texture_resolution tem precedência.
Name
remove_lighting
Type
boolean
padrão true
Description
Remove realces e sombras da textura de cor base, produzindo um resultado mais limpo que funciona melhor sob configurações de iluminação personalizadas.
Suportado apenas quando ai_model é meshy-6.
Name
target_formats
Type
string[]
Description
Especifica quais formatos de arquivo 3D incluir na saída. Somente 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
padrão false
Description
Quando definido como true, a tarefa renderiza adicionalmente uma versão com fundo transparente (RGBA) do preview e a retorna como alpha_thumbnail_url na resposta GET. O campo thumbnail_url existente permanece inalterado.
Retornos
A propriedade result da resposta contém o id da tarefa da nova tarefa de Retexturizar criada.
Modos de Falha
Name
400 - Bad Request
Description
A requisição foi inaceitável. Causas comuns:
Parâmetro ausente: model_url ou input_task_id deve ser fornecido.
Estilo ausente: um dos parâmetros 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 multivista: multiview_image_urls requer explicitamente ai_model: "meshy-7".
Modelo não disponível: ai_model: "meshy-7" e ai_model: "meshy-6-lite" estão sendo lançados progressivamente e podem ainda não estar habilitados para sua conta.
Tarefa de entrada inválida: input_task_id deve se referir a uma tarefa bem-sucedida de um modelo suportado.
Formato de modelo inválido: model_url aponta para um arquivo com extensão não suportada.
URL inacessível: não foi possível baixar model_url, image_style_url ou um elemento de multiview_image_urls.
Name
401 - Unauthorized
Description
Falha na autenticação. Verifique sua chave de API.
Name
402 - Payment Required
Description
Créditos insuficientes para realizar esta tarefa.
Name
429 - Too Many Requests
Description
Você excedeu seu limite de taxa.
Request
POST
/openapi/v1/retexture
# Retexture with text promptcurlhttps://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": "red fangs, Samurai outfit that fused with japanese batik style", "enable_original_uv": true, "enable_pbr": true }'# Retexture with image style and 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 recuperar uma tarefa de Retexturização a partir de um id de tarefa válido.
Consulte O Objeto de Tarefa de Retexturização para ver quais
propriedades estão incluídas no objeto de tarefa de Retexturização.
Parâmetros
Name
id
Type
path
Description
Identificador único da tarefa de Retexturização a ser recuperada.
{"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":"red fangs, Samurai outfit that fused with japanese batik style","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}
Este endpoint exclui permanentemente uma tarefa de retexturização, incluindo todos os modelos e dados associados. Esta ação é irreversível.
Parâmetros de Caminho
Name
id
Type
path
Description
O ID da tarefa de retexturização a ser excluída.
Status da Tarefa
Uma tarefa que ainda está PENDING é excluída e os créditos consumidos no
momento da criação são reembolsados.
Uma tarefa que já está IN_PROGRESS não pode ser excluída: a requisição é
rejeitada com 409 Conflict e a tarefa continua em execução. Créditos de uma
tarefa que o worker já iniciou não são reembolsáveis, então excluí-la no meio
da execução custaria tanto os créditos quanto o resultado. Aguarde até que
ela alcance SUCCEEDED, FAILED ou CANCELED, e então a exclua.
Uma tarefa em um estado terminal (SUCCEEDED, FAILED ou CANCELED) é
excluída sem reembolso.
Retornos
Retorna 200 OK em caso de sucesso, ou 409 Conflict quando a tarefa está
IN_PROGRESS.
// 200 OK on success, with an empty body.//// 409 Conflict when the task is IN_PROGRESS — the task is left 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."}
[ {"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":"red fangs, Samurai outfit that fused with japanese batik style","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 }]
O objeto Retexture Task é uma unidade de trabalho que a Meshy usa para gerar uma textura 3D a partir de entradas de texto ou imagem.
O modelo possui as seguintes propriedades:
Propriedades
Name
id
Type
string
Description
Identificador único da tarefa. Embora usemos um UUID k-sortable para os ids de tarefas como
detalhe de implementação, você não deve fazer suposições sobre o formato do id.
Name
type
Type
string
Description
Tipo da tarefa de Retexturizar. O valor é retexture.
Name
model_urls
Type
object
Description
URL para download do arquivo de modelo 3D texturizado gerado pela Meshy.
Name
glb
Type
string
Description
URL para download do arquivo GLB.
Name
fbx
Type
string
Description
URL para download do arquivo FBX.
Name
obj
Type
string
Description
URL para download do arquivo OBJ.
Name
usdz
Type
string
Description
URL para download do arquivo USDZ.
Name
mtl
Type
string
Description
URL para download do arquivo MTL, retornado junto com as exportações OBJ quando há texturas presentes.
Name
stl
Type
string
Description
URL para download do arquivo STL.
Name
3mf
Type
string
Description
URL para download do arquivo 3MF. Presente apenas quando 3mf foi solicitado via target_formats.
Name
text_style_prompt
Type
string
Description
Este é o prompt de texto que foi usado para criar a tarefa de texturização.
Name
image_style_url
Type
string
Description
Esta é a imagem de entrada que foi usada para criar a tarefa de texturização.
Name
multiview_image_urls
Type
string[]
Description
URLs para download das imagens de referência em Multivista que foram usadas para criar a tarefa de texturização. Presente apenas quando a tarefa foi criada com multiview_image_urls.
Name
thumbnail_url
Type
string
Description
URL para download da imagem de miniatura do arquivo do modelo.
Name
alpha_thumbnail_url
Type
string
Description
URL para download de uma versão com fundo transparente (RGBA) de thumbnail_url. Presente apenas quando a tarefa foi criada com alpha_thumbnail: true e a pré-visualização transparente foi renderizada com sucesso; caso contrário, esse campo é omitido.
Name
progress
Type
integer
Description
Progresso da tarefa. Se a tarefa ainda não foi iniciada, essa propriedade será 0. Assim que a tarefa for concluída com sucesso, isso 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 foi iniciada, essa 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, 12:00:00 PM GMT é representado como 1693569600000. Isso se aplica
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, essa 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
Um array de objetos de URL de textura que são gerados a partir da tarefa. Normalmente isso contém apenas um objeto de URL de textura. Cada URL de textura tem as seguintes propriedades:
Name
base_color
Type
string
Description
URL para download da imagem do mapa de cor base.
Name
metallic
Type
string
Description
URL para download da imagem do mapa metálico.
Se a tarefa for criada com enable_pbr: false, essa propriedade será omitida.
Name
normal
Type
string
Description
URL para download da imagem do mapa de normais.
Se a tarefa for criada com enable_pbr: false, essa propriedade será omitida.
Name
roughness
Type
string
Description
URL para download da imagem do mapa de rugosidade.
Se a tarefa for criada com enable_pbr: false, essa propriedade será omitida.
Name
emission
Type
string
Description
URL para download da imagem do mapa de emissão.
Se a tarefa for criada com enable_pbr: false, ou ai_model for meshy-6-lite, essa propriedade será omitida.
Name
preceding_tasks
Type
integer
Description
A contagem de tarefas precedentes.
Essa propriedade só está presente quando o status da tarefa é PENDING.
Name
task_error
Type
object
Description
Detalhes de erro para tarefas com falha. Consulte 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":"red fangs, Samurai outfit that fused with japanese batik style","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}