Retexture API

Ang Retexture API ay isang feature na nagbibigay-daan sa iyo na i-integrate ang mga kakayahan ng AI Retexture ng Meshy sa sarili mong application. Sa seksyong ito, makikita mo ang lahat ng impormasyong kailangan mo upang makapagsimula sa API na ito.


POST/openapi/v1/retexture

Gumawa ng Retexture Task

Pinapayagan ka ng endpoint na ito na gumawa ng bagong Retexture task. Sumangguni sa The Retexture Task Object para makita kung aling mga property ang kasama sa Retexture task object.

Mga Parameter

  • Name
    input_task_id
    Type
    string
    Kinakailangan
    Description

    Ang ID ng nakumpletong Image to 3D o Text to 3D task na nais mong i-retexture. Ang task na ito ay dapat isa sa mga sumusunod na task: Text to 3D Preview, Text to 3D Refine, Image to 3D o Remesh. Bukod dito, dapat mayroon itong status na SUCCEEDED.

  • Name
    model_url
    Type
    string
    Kinakailangan
    Description

    Magbigay ng 3D model para lagyan ng texture ng Meshy. Mga sinusuportahang format: .glb, .gltf, .obj, .fbx, .stl.

    May dalawang paraan para ibigay ang model:

    • URL na pampublikong naa-access: Isang URL na naa-access mula sa pampublikong internet.
    • Data URI: Isang base64-encoded na data URI ng model. Gamitin ang MIME type na application/octet-stream. Halimbawa: data:application/octet-stream;base64,<your base64-encoded model data>.
  • Name
    text_style_prompt
    Type
    string
    Kinakailangan
    Description

    Ilarawan gamit ang text ang nais mong texture style ng object. Maximum na 600 character.

  • Name
    image_style_url
    Type
    string
    Kinakailangan
    Description

    Magbigay ng 2d image para gabayan ang proseso ng paglalagay ng texture. Kasalukuyan naming sinusuportahan ang mga format na .jpg, .jpeg, at .png.

    May dalawang paraan para ibigay ang image:

    • URL na pampublikong naa-access: Isang URL na naa-access mula sa pampublikong internet
    • Data URI: Isang base64-encoded na data URI ng image. Halimbawa ng data URI: data:image/jpeg;base64,<your base64-encoded image data>
  • Name
    ai_model
    Type
    string
    default latest
    Description

    ID ng AI model na gagamitin para sa retexturing. Mga available na value: meshy-5, meshy-6, latest (Meshy 6).

  • Name
    enable_original_uv
    Type
    boolean
    default false
    Description

    Panatilihin ang kasalukuyang UV layout ng model sa halip na bumuo ng bago.

    • Kung nire-retexture mo ang isang model na binuo ng Meshy (sa pamamagitan ng input_task_id, o isang model_url na tumuturo sa output ng Meshy), itakda ito sa true para muling gamitin ang optimized na UV layout nito.
    • Kung nire-retexture mo ang isang third-party model na in-upload mo, itakda sa true kapag mayroon na itong magagandang UV na nais mong panatilihin, o iwan itong false para hayaang gumawa ang Meshy ng bagong UVs (pinakamainam para sa mga model na walang wastong UV mapping).
  • Name
    enable_pbr
    Type
    boolean
    default false
    Description

    Bumuo ng PBR maps (metallic, roughness, normal) bilang karagdagan sa base color. Kasama rin ang emission map kapag ang ai_model ay meshy-6 o latest.

  • Name
    hd_texture
    Type
    boolean
    default false
    Description

    Bumuo ng base color texture sa 4K (4096×4096) resolution para sa mas mataas na detalye.

  • Name
    remove_lighting
    Type
    boolean
    default true
    Description

    Inaalis ang highlights at shadows mula sa base color texture, na naglalabas ng mas malinis na resulta na mas mahusay gumana sa ilalim ng custom na lighting setup.

  • Name
    target_formats
    Type
    string[]
    Description

    Tinutukoy kung aling mga 3D file format ang isasama sa output. Tanging ang mga hiniling na format lamang ang bubuuin at ibabalik, na maaaring magpababa sa oras ng pagkumpleto ng task. Kapag hindi inilagay, kasama ang lahat ng sinusuportahang format.

    Mga available na value: glb, obj, fbx, stl, usdz, 3mf

  • Name
    alpha_thumbnail
    Type
    boolean
    default false
    Description

    Kapag itinakda sa true, karagdagang nire-render ng task ang isang transparent-background (RGBA) na bersyon ng preview at ibinabalik ito bilang alpha_thumbnail_url sa GET response. Hindi nababago ang kasalukuyang field na thumbnail_url.

Mga Ibinabalik

Ang result property ng response ay naglalaman ng task id ng bagong likhang Retexture task.

Mga Mode ng Pagkabigo

  • Name
    400 - Bad Request
    Description

    Hindi katanggap-tanggap ang request. Mga karaniwang sanhi:

    • Nawawalang parameter: Dapat ibigay ang alinman sa model_url o input_task_id.
    • Nawawalang style: Dapat ibigay ang alinman sa text_style_prompt o image_style_url.
    • Invalid na input task: Ang input_task_id ay dapat tumukoy sa isang successful na task mula sa sinusuportahang model.
    • Invalid na model format: Ang model_url ay tumuturo sa isang file na may hindi sinusuportahang extension.
    • Hindi maabot na URL: Hindi ma-download ang model_url o image_style_url.
  • Name
    401 - Unauthorized
    Description

    Nabigo ang authentication. Pakisuri ang iyong API key.

  • Name
    402 - Payment Required
    Description

    Hindi sapat ang credits para isagawa ang task na ito.

  • Name
    429 - Too Many Requests
    Description

    Lumampas ka sa iyong rate limit.

Request

POST
/openapi/v1/retexture
# Retexture with text prompt
curl https://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 PBR
curl https://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
  }'

Response

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

GET/openapi/v1/retexture/:id

Kunin ang isang Retexture Task

Pinapayagan ka ng endpoint na ito na kunin ang isang Retexture task gamit ang valid na task id. Sumangguni sa Ang Retexture Task Object upang makita kung aling mga property ang kasama sa Retexture task object.

Mga Parameter

  • Name
    id
    Type
    path
    Description

    Natatanging identifier para sa Retexture task na kukunin.

Mga Ibinabalik

Naglalaman ang response ng Retexture task object. Tingnan ang seksyong Ang Retexture Task Object para sa mga detalye.

Request

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

Response

{
  "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
}

DELETE/openapi/v1/retexture/:id

Tanggalin ang Retexture Task

Permanenteng dine-delete ng endpoint na ito ang isang retexture task, kasama ang lahat ng kaugnay na mga modelo at data. Hindi na maibabalik ang aksyong ito.

Mga Path Parameter

  • Name
    id
    Type
    path
    Description

    Ang ID ng retexture task na ide-delete.

Mga Ibinabalik

Nagbabalik ng 200 OK kapag matagumpay.

Request

DELETE
/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v1/retexture/a43b5c6d-7e8f-901a-234b-567c890d1e2f \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 200 Ok on success.


GET/openapi/v1/retexture

Ilista ang mga Retexture Task

Pinapayagan ka ng endpoint na ito na kunin ang listahan ng mga Retexture task.

Mga Parameter

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Numero ng pahina para sa pagination.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Limitasyon sa laki ng pahina. Ang pinakamataas na pinapayagan ay 50 item.

  • Name
    sort_by
    Type
    string
    Description

    Field na pag-uuriin ayon dito.

    Mga available na value:

    • +created_at: I-sort ayon sa oras ng paggawa sa pataas na pagkakasunod-sunod.
    • -created_at: I-sort ayon sa oras ng paggawa sa pababang pagkakasunod-sunod.

Mga Ibinabalik

Nagbabalik ng naka-pagination na listahan ng Mga Retexture Task Object.

Request

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

Response

[
  {
    "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
  }
]

GET/openapi/v1/retexture/:id/stream

I-stream ang Retexture Task

Ang endpoint na ito ay nag-i-stream ng mga real-time na update para sa isang Retexture task gamit ang Server-Sent Events (SSE).

Mga Parameter

  • Name
    id
    Type
    path
    Description

    Natatanging identifier para sa Retexture task na i-stream.

Mga Ibinabalik

Nagbabalik ng stream ng Mga Object ng Retexture Task bilang Server-Sent Events.

Para sa mga task na PENDING o IN_PROGRESS, isasama lang ng response stream ang kinakailangang mga field na progress at status.

Request

GET
/openapi/v1/retexture/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v1/retexture/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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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": "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
}

Ang Retexture Task Object

Ang Retexture Task object ay isang yunit ng trabaho na ginagamit ng Meshy upang makabuo ng 3D texture mula sa alinman sa text o image inputs. Ang model ay may sumusunod na mga property:

Mga Property

  • Name
    id
    Type
    string
    Description

    Natatanging identifier para sa task. Bagama't gumagamit kami ng k-sortable UUID para sa mga task id bilang detalye ng implementation, hindi ka dapat gumawa ng anumang palagay tungkol sa format ng id.

  • Name
    type
    Type
    string
    Description

    Uri ng Retexture task. Ang value ay retexture.

  • Name
    model_urls
    Type
    object
    Description

    Nada-download na URL sa naka-texture na 3D model file na ginawa ng Meshy.

    • Name
      glb
      Type
      string
      Description

      Nada-download na URL sa GLB file.

    • Name
      fbx
      Type
      string
      Description

      Nada-download na URL sa FBX file.

    • Name
      obj
      Type
      string
      Description

      Nada-download na URL sa OBJ file.

    • Name
      usdz
      Type
      string
      Description

      Nada-download na URL sa USDZ file.

    • Name
      mtl
      Type
      string
      Description

      Nada-download na URL sa MTL file, na ibinabalik kasama ng mga OBJ export kapag may mga texture.

    • Name
      stl
      Type
      string
      Description

      Nada-download na URL sa STL file.

    • Name
      3mf
      Type
      string
      Description

      Nada-download na URL sa 3MF file. Naroroon lang kapag hiniling ang 3mf sa pamamagitan ng target_formats.

  • Name
    text_style_prompt
    Type
    string
    Description

    Ito ang text prompt na ginamit upang gawin ang texturing task.

  • Name
    image_style_url
    Type
    string
    Description

    Ito ang image input na ginamit upang gawin ang texturing task.

  • Name
    thumbnail_url
    Type
    string
    Description

    Nada-download na URL sa thumbnail na larawan ng model file.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    Nada-download na URL sa bersyong may transparent na background (RGBA) ng thumbnail_url. Naroroon lang kapag ginawa ang task gamit ang alpha_thumbnail: true at matagumpay na na-render ang transparent preview; kung hindi, aalisin ang field na ito.

  • Name
    progress
    Type
    integer
    Description

    progress ng task. Kung hindi pa nagsisimula ang task, magiging 0 ang property na ito. Kapag nagtagumpay na ang task, magiging 100 ito.

  • Name
    started_at
    Type
    timestamp
    Description

    timestamp kung kailan nagsimula ang task, sa milliseconds. Kung hindi pa nagsisimula ang task, magiging 0 ang property na ito.

  • Name
    created_at
    Type
    timestamp
    Description

    timestamp kung kailan ginawa ang task, sa milliseconds.

  • Name
    expires_at
    Type
    timestamp
    Description

    timestamp kung kailan mag-e-expire ang resulta ng task, sa milliseconds.

  • Name
    finished_at
    Type
    timestamp
    Description

    timestamp kung kailan natapos ang task, sa milliseconds. Kung hindi pa tapos ang task, magiging 0 ang property na ito.

  • Name
    status
    Type
    string
    Description

    Status ng task. Ang mga posibleng value ay isa sa PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    texture_urls
    Type
    array
    Description

    Isang array ng mga texture URL object na nabuo mula sa task. Karaniwan, naglalaman lang ito ng isang texture URL object. Ang bawat texture URL ay may mga sumusunod na property:

    • Name
      base_color
      Type
      string
      Description

      Nada-download na URL sa base color map image.

    • Name
      metallic
      Type
      string
      Description

      Nada-download na URL sa metallic map image.

    • Name
      normal
      Type
      string
      Description

      Nada-download na URL sa normal map image.

    • Name
      roughness
      Type
      string
      Description

      Nada-download na URL sa roughness map image.

    • Name
      emission
      Type
      string
      Description

      Nada-download na URL sa emission map image.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Ang bilang ng mga nauunang task.

  • Name
    task_error
    Type
    object
    Description

    Mga detalye ng error para sa mga nabigong task. Tingnan ang Errors para sa buong sanggunian ng task_error object.

  • Name
    consumed_credits
    Type
    integer
    Description

    Ang bilang ng credits na nagamit ng task na ito. Naroroon kapag ang status ng task ay PENDING, IN_PROGRESS, o SUCCEEDED. Nagbabalik ng 0 para sa mga FAILED na task (ibinabalik ang credits kapag nabigo).

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
}