Retexture API

Retexture API adalah fitur yang memungkinkan Anda mengintegrasikan kemampuan Retexture AI Meshy ke dalam aplikasi Anda sendiri. Di bagian ini, Anda akan menemukan semua informasi yang Anda perlukan untuk memulai dengan API ini.


POST/openapi/v1/retexture

Buat Tugas Retexture

endpoint ini memungkinkan Anda membuat tugas Retexture baru. Lihat Objek Tugas Retexture untuk mengetahui properti apa saja yang disertakan dalam objek tugas Retexture.

Parameter

  • Name
    input_task_id
    Type
    string
    Wajib
    Description

    ID tugas Gambar ke 3D atau Teks ke 3D yang telah selesai dan ingin Anda Retexture. Tugas ini harus merupakan salah satu dari tugas berikut: Pratinjau Teks ke 3D, Penyempurnaan Teks ke 3D, Gambar ke 3D, atau Remesh. Selain itu, tugas tersebut harus memiliki status SUCCEEDED.

  • Name
    model_url
    Type
    string
    Wajib
    Description

    Berikan model 3D untuk diberi tekstur oleh Meshy. Format yang didukung: .glb, .gltf, .obj, .fbx, .stl.

    Ada dua cara untuk memberikan model:

    • URL yang dapat diakses publik: URL yang dapat diakses dari internet publik.
    • Data URI: Data URI model yang dienkode base64. Gunakan MIME type application/octet-stream. Contoh: data:application/octet-stream;base64,<your base64-encoded model data>.
  • Name
    text_style_prompt
    Type
    string
    Wajib
    Description

    Jelaskan gaya tekstur objek yang Anda inginkan menggunakan teks. Maksimum 600 karakter.

  • Name
    image_style_url
    Type
    string
    Wajib
    Description

    Berikan gambar 2D untuk memandu proses pemberian tekstur. Saat ini kami mendukung format .jpg, .jpeg, dan .png.

    Ada dua cara untuk memberikan gambar:

    • URL yang dapat diakses publik: URL yang dapat diakses dari internet publik
    • Data URI: Data URI gambar yang dienkode base64. Contoh data URI: data:image/jpeg;base64,<your base64-encoded image data>
  • Name
    ai_model
    Type
    string
    default latest
    Description

    ID model AI yang akan digunakan untuk Retexture. Nilai yang tersedia: meshy-5, meshy-6, latest (Meshy 6).

  • Name
    enable_original_uv
    Type
    boolean
    default false
    Description

    Pertahankan tata letak UV yang sudah ada pada model alih-alih membuat yang baru.

    • Jika Anda melakukan Retexture pada model yang dihasilkan Meshy (melalui input_task_id, atau model_url yang mengarah ke output Meshy), atur ini ke true untuk menggunakan kembali tata letak UV yang telah dioptimalkan.
    • Jika Anda melakukan Retexture pada model pihak ketiga yang Anda unggah, atur true ketika model tersebut sudah memiliki UV yang baik dan ingin Anda pertahankan, atau biarkan false agar Meshy membuka UV baru (terbaik untuk model yang tidak memiliki pemetaan UV yang tepat).
  • Name
    enable_pbr
    Type
    boolean
    default false
    Description

    Hasilkan peta PBR (metallic, roughness, normal) selain warna dasar. Peta emission juga disertakan ketika ai_model adalah meshy-6 atau latest.

  • Name
    hd_texture
    Type
    boolean
    default false
    Description

    Hasilkan tekstur warna dasar pada resolusi 4K (4096×4096) untuk detail yang lebih tinggi.

  • Name
    remove_lighting
    Type
    boolean
    default true
    Description

    Menghapus highlight dan bayangan dari tekstur warna dasar, menghasilkan hasil yang lebih bersih dan bekerja lebih baik di bawah pengaturan pencahayaan kustom.

  • Name
    target_formats
    Type
    string[]
    Description

    Menentukan format file 3D mana yang akan disertakan dalam output. Hanya format yang diminta yang akan dihasilkan dan dikembalikan, yang dapat mengurangi waktu penyelesaian tugas. Jika dihilangkan, semua format yang didukung disertakan.

    Nilai yang tersedia: glb, obj, fbx, stl, usdz, 3mf

  • Name
    alpha_thumbnail
    Type
    boolean
    default false
    Description

    Ketika diatur ke true, tugas juga merender versi pratinjau dengan latar belakang transparan (RGBA) dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Field thumbnail_url yang sudah ada tidak berubah.

Mengembalikan

Properti result dari respons berisi id tugas dari tugas Retexture yang baru dibuat.

Mode Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak dapat diterima. Penyebab umum:

    • Parameter hilang: Salah satu dari model_url atau input_task_id harus diberikan.
    • Gaya hilang: Salah satu dari text_style_prompt atau image_style_url harus diberikan.
    • Tugas input tidak valid: input_task_id harus merujuk ke tugas yang berhasil dari model yang didukung.
    • Format model tidak valid: model_url mengarah ke file dengan ekstensi yang tidak didukung.
    • URL tidak dapat dijangkau: model_url atau image_style_url tidak dapat diunduh.
  • Name
    401 - Unauthorized
    Description

    Autentikasi gagal. Harap periksa kunci API Anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak mencukupi untuk melakukan tugas ini.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melampaui batas laju Anda.

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

Mengambil Tugas Retexture

endpoint ini memungkinkan Anda mengambil tugas Retexture dengan id yang valid. Lihat Objek Tugas Retexture untuk mengetahui properti yang disertakan dalam objek tugas Retexture.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengidentifikasi unik untuk tugas Retexture yang akan diambil.

Mengembalikan

Respons berisi objek tugas Retexture. Lihat bagian Objek Tugas Retexture untuk detailnya.

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

Hapus Tugas Retexture

endpoint ini menghapus tugas retexture secara permanen, termasuk semua model dan data terkait. Tindakan ini tidak dapat dibatalkan.

Parameter Path

  • Name
    id
    Type
    path
    Description

    ID tugas retexture yang akan dihapus.

Pengembalian

Mengembalikan 200 OK jika berhasil.

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

Daftar Tugas Retexture

endpoint ini memungkinkan Anda mengambil daftar tugas Retexture.

Parameter

  • Name
    page_num
    Type
    integer
    default 1
    Description

    Nomor halaman untuk paginasi.

  • Name
    page_size
    Type
    integer
    default 10
    Description

    Batas ukuran halaman. Maksimum yang diizinkan adalah 50 item.

  • Name
    sort_by
    Type
    string
    Description

    Bidang untuk diurutkan berdasarkan.

    Nilai yang tersedia:

    • +created_at: Urutkan berdasarkan waktu pembuatan dalam urutan naik.
    • -created_at: Urutkan berdasarkan waktu pembuatan dalam urutan turun.

Mengembalikan

Mengembalikan daftar berpaginasi dari Objek Tugas Retexture.

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

Streaming Tugas Retexture

endpoint ini mengalirkan pembaruan real-time untuk tugas Retexture menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengidentifikasi unik untuk tugas Retexture yang akan di-stream.

Mengembalikan

Mengembalikan stream Objek Tugas Retexture sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, stream respons hanya akan menyertakan field progress dan status yang diperlukan.

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
}

Objek Tugas Retexture

Objek Tugas Retexture adalah unit kerja yang digunakan Meshy untuk menghasilkan tekstur 3D dari input teks atau gambar. Model ini memiliki properti berikut:

Properti

  • Name
    id
    Type
    string
    Description

    Pengidentifikasi unik untuk tugas. Meskipun kami menggunakan UUID yang dapat diurutkan-k untuk id tugas sebagai detail implementasi, Anda tidak boleh membuat asumsi apa pun tentang format id.

  • Name
    type
    Type
    string
    Description

    Jenis tugas Retexture. Nilainya adalah retexture.

  • Name
    model_urls
    Type
    object
    Description

    URL yang dapat diunduh untuk file model 3D bertekstur yang dihasilkan oleh Meshy.

    • Name
      glb
      Type
      string
      Description

      URL yang dapat diunduh untuk file GLB.

    • Name
      fbx
      Type
      string
      Description

      URL yang dapat diunduh untuk file FBX.

    • Name
      obj
      Type
      string
      Description

      URL yang dapat diunduh untuk file OBJ.

    • Name
      usdz
      Type
      string
      Description

      URL yang dapat diunduh untuk file USDZ.

    • Name
      mtl
      Type
      string
      Description

      URL yang dapat diunduh untuk file MTL, dikembalikan bersama ekspor OBJ saat tekstur tersedia.

    • Name
      stl
      Type
      string
      Description

      URL yang dapat diunduh untuk file STL.

    • Name
      3mf
      Type
      string
      Description

      URL yang dapat diunduh untuk file 3MF. Hanya ada saat 3mf diminta melalui target_formats.

  • Name
    text_style_prompt
    Type
    string
    Description

    Ini adalah prompt teks yang digunakan untuk membuat tugas pemberian tekstur.

  • Name
    image_style_url
    Type
    string
    Description

    Ini adalah input gambar yang digunakan untuk membuat tugas pemberian tekstur.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL yang dapat diunduh untuk gambar thumbnail dari file model.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL yang dapat diunduh untuk versi berlatar belakang transparan (RGBA) dari thumbnail_url. Hanya ada saat tugas dibuat dengan alpha_thumbnail: true dan pratinjau transparan berhasil dirender; jika tidak, bidang ini dihilangkan.

  • Name
    progress
    Type
    integer
    Description

    Progress tugas. Jika tugas belum dimulai, properti ini akan menjadi 0. Setelah tugas berhasil, nilainya akan menjadi 100.

  • Name
    started_at
    Type
    timestamp
    Description

    Stempel waktu saat tugas dimulai, dalam milidetik. Jika tugas belum dimulai, properti ini akan menjadi 0.

  • Name
    created_at
    Type
    timestamp
    Description

    Stempel waktu saat tugas dibuat, dalam milidetik.

  • Name
    expires_at
    Type
    timestamp
    Description

    Stempel waktu saat hasil tugas kedaluwarsa, dalam milidetik.

  • Name
    finished_at
    Type
    timestamp
    Description

    Stempel waktu saat tugas selesai, dalam milidetik. Jika tugas belum selesai, properti ini akan menjadi 0.

  • Name
    status
    Type
    string
    Description

    Status tugas. Nilai yang mungkin adalah salah satu dari PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    texture_urls
    Type
    array
    Description

    Array objek URL tekstur yang dihasilkan dari tugas. Biasanya ini hanya berisi satu objek URL tekstur. Setiap URL tekstur memiliki properti berikut:

    • Name
      base_color
      Type
      string
      Description

      URL yang dapat diunduh untuk gambar map warna dasar.

    • Name
      metallic
      Type
      string
      Description

      URL yang dapat diunduh untuk gambar map metallic.

    • Name
      normal
      Type
      string
      Description

      URL yang dapat diunduh untuk gambar normal map.

    • Name
      roughness
      Type
      string
      Description

      URL yang dapat diunduh untuk gambar map roughness.

    • Name
      emission
      Type
      string
      Description

      URL yang dapat diunduh untuk gambar map emission.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Jumlah tugas sebelumnya.

  • Name
    task_error
    Type
    object
    Description

    Detail kesalahan untuk tugas yang gagal. Lihat Kesalahan untuk referensi objek task_error lengkap.

  • Name
    consumed_credits
    Type
    integer
    Description

    Jumlah kredit yang digunakan oleh tugas ini. Ada saat status tugas adalah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugas FAILED (kredit dikembalikan saat terjadi kegagalan).

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
}