API Retekstur

API Retekstur ialah ciri yang membolehkan anda mengintegrasikan keupayaan Retekstur AI Meshy ke dalam aplikasi anda sendiri. Dalam bahagian ini, anda akan menemui semua maklumat yang anda perlukan untuk bermula dengan API ini.


POST/openapi/v1/retexture

Cipta Tugas Retekstur

Endpoint ini membolehkan anda mencipta tugas Retekstur baharu. Rujuk Objek Tugas Retekstur untuk melihat properti yang disertakan dengan objek tugas Retekstur.

Parameter

  • Name
    input_task_id
    Type
    string
    Diperlukan
    Description

    ID tugas Imej ke 3D atau Teks ke 3D yang telah selesai yang ingin anda retekstur. Tugas ini mestilah salah satu daripada tugas berikut: Pratonton Teks ke 3D, Perhalus Teks ke 3D, Imej ke 3D atau Remesh. Selain itu, tugas tersebut mesti mempunyai status SUCCEEDED.

  • Name
    model_url
    Type
    string
    Diperlukan
    Description

    Sediakan model 3D untuk Meshy teksturkan. Format yang disokong: .glb, .gltf, .obj, .fbx, .stl.

    Terdapat dua cara untuk menyediakan model:

    • URL yang boleh diakses secara awam: URL yang boleh diakses daripada internet awam.
    • Data URI: Data URI model yang dikodkan base64. Gunakan MIME type application/octet-stream. Contoh: data:application/octet-stream;base64,<your base64-encoded model data>.
  • Name
    text_style_prompt
    Type
    string
    Diperlukan
    Description

    Huraikan gaya tekstur objek yang anda inginkan menggunakan teks. Maksimum 600 aksara.

  • Name
    image_style_url
    Type
    string
    Diperlukan
    Description

    Sediakan imej 2D untuk memandu proses penteksturan. Kami kini menyokong format .jpg, .jpeg, dan .png.

    Terdapat dua cara untuk menyediakan imej:

    • URL yang boleh diakses secara awam: URL yang boleh diakses daripada internet awam
    • Data URI: Data URI imej yang dikodkan base64. Contoh Data URI: data:image/jpeg;base64,<your base64-encoded image data>
  • Name
    ai_model
    Type
    string
    lalai latest
    Description

    ID model AI untuk digunakan bagi retekstur. Nilai tersedia: meshy-5, meshy-6, latest (Meshy 6).

  • Name
    enable_original_uv
    Type
    boolean
    lalai false
    Description

    Kekalkan susun atur UV sedia ada model dan bukannya menjana yang baharu.

    • Jika anda sedang melakukan retekstur pada model yang dijana oleh Meshy (melalui input_task_id, atau model_url yang menunjuk kepada output Meshy), tetapkan ini kepada true untuk menggunakan semula susun atur UV yang dioptimumkan.
    • Jika anda sedang melakukan retekstur pada model pihak ketiga yang anda muat naik, tetapkan true apabila model tersebut sudah mempunyai UV yang baik yang ingin anda kekalkan, atau biarkan ia false untuk membenarkan Meshy membentangkan UV baharu (terbaik untuk model yang tiada pemetaan UV yang betul).
  • Name
    enable_pbr
    Type
    boolean
    lalai false
    Description

    Jana peta PBR (metallic, roughness, normal) sebagai tambahan kepada warna asas. Peta emission juga disertakan apabila ai_model ialah meshy-6 atau latest.

  • Name
    hd_texture
    Type
    boolean
    lalai false
    Description

    Jana tekstur warna asas pada resolusi 4K (4096×4096) untuk butiran yang lebih tinggi.

  • Name
    remove_lighting
    Type
    boolean
    lalai true
    Description

    Mengalih keluar sorotan dan bayang daripada tekstur warna asas, menghasilkan output yang lebih bersih dan berfungsi dengan lebih baik di bawah tetapan pencahayaan tersuai.

  • Name
    target_formats
    Type
    string[]
    Description

    Menentukan format fail 3D yang akan disertakan dalam output. Hanya format yang diminta akan dijana dan dikembalikan, yang boleh mengurangkan masa penyelesaian tugas. Apabila ditinggalkan, semua format yang disokong disertakan.

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

  • Name
    alpha_thumbnail
    Type
    boolean
    lalai false
    Description

    Apabila ditetapkan kepada true, tugas ini turut merender versi pratonton berlatar belakang telus (RGBA) dan mengembalikannya sebagai alpha_thumbnail_url pada respons GET. Medan thumbnail_url sedia ada tidak berubah.

Pulangan

Properti result dalam respons mengandungi id tugas bagi tugas Retekstur yang baharu dicipta.

Mod Kegagalan

  • Name
    400 - Bad Request
    Description

    Permintaan tidak boleh diterima. Punca biasa:

    • Parameter hilang: Sama ada model_url atau input_task_id mesti disediakan.
    • Gaya hilang: Sama ada text_style_prompt atau image_style_url mesti disediakan.
    • Tugas input tidak sah: input_task_id mesti merujuk kepada tugas yang berjaya daripada model yang disokong.
    • Format model tidak sah: model_url menunjuk kepada fail dengan sambungan yang tidak disokong.
    • URL tidak dapat dicapai: model_url atau image_style_url tidak dapat dimuat turun.
  • Name
    401 - Unauthorized
    Description

    Pengesahan gagal. Sila semak kunci API anda.

  • Name
    402 - Payment Required
    Description

    Kredit tidak mencukupi untuk melaksanakan tugas ini.

  • Name
    429 - Too Many Requests
    Description

    Anda telah melebihi had kadar 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

Dapatkan Semula Tugas Retekstur

Endpoint ini membolehkan anda mendapatkan semula tugas Retekstur dengan id tugas yang sah. Rujuk Objek Tugas Retekstur untuk melihat sifat yang disertakan dalam objek tugas Retekstur.

Parameter

  • Name
    id
    Type
    path
    Description

    Pengecam unik untuk tugas Retekstur yang hendak didapatkan semula.

Mengembalikan

Respons mengandungi objek tugas Retekstur. Semak bahagian Objek Tugas Retekstur untuk butiran.

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

Padam Tugas Retekstur

endpoint ini memadamkan tugas retekstur secara kekal, termasuk semua model dan data yang berkaitan. Tindakan ini tidak boleh dipulihkan.

Parameter Laluan

  • Name
    id
    Type
    path
    Description

    ID tugas retekstur untuk dipadam.

Mengembalikan

Mengembalikan 200 OK apabila berjaya.

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

Senaraikan Tugas Retekstur

Endpoint ini membolehkan anda mendapatkan senarai tugas Retekstur.

Parameter

  • Name
    page_num
    Type
    integer
    lalai 1
    Description

    Nombor halaman untuk penomboran halaman.

  • Name
    page_size
    Type
    integer
    lalai 10
    Description

    Had saiz halaman. Maksimum yang dibenarkan ialah 50 item.

  • Name
    sort_by
    Type
    string
    Description

    Medan untuk diisih mengikut.

    Nilai yang tersedia:

    • +created_at: Isih mengikut masa penciptaan dalam tertib menaik.
    • -created_at: Isih mengikut masa penciptaan dalam tertib menurun.

Pulangan

Mengembalikan senarai Objek Tugas Retekstur yang dipaginasikan.

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

Strim Tugas Retekstur

endpoint ini menstrim kemas kini masa nyata untuk tugas Retekstur menggunakan Server-Sent Events (SSE).

Parameter

  • Name
    id
    Type
    path
    Description

    Pengenal pasti unik untuk tugas Retekstur yang akan distrim.

Pulangan

Mengembalikan strim Objek Tugas Retekstur sebagai Server-Sent Events.

Untuk tugas PENDING atau IN_PROGRESS, strim respons hanya akan menyertakan medan 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 Retekstur

Objek Tugas Retekstur ialah unit kerja yang digunakan oleh Meshy untuk menjana tekstur 3D daripada input teks atau imej. Model ini mempunyai sifat berikut:

Sifat

  • Name
    id
    Type
    string
    Description

    Pengecam unik untuk tugasan. Walaupun kami menggunakan UUID boleh diisih-k sebagai butiran pelaksanaan bagi id tugasan, anda tidak harus membuat sebarang andaian tentang format id.

  • Name
    type
    Type
    string
    Description

    Jenis tugasan Retekstur. Nilainya ialah retexture.

  • Name
    model_urls
    Type
    object
    Description

    URL boleh dimuat turun untuk fail model 3D bertekstur yang dijana oleh Meshy.

    • Name
      glb
      Type
      string
      Description

      URL boleh dimuat turun untuk fail GLB.

    • Name
      fbx
      Type
      string
      Description

      URL boleh dimuat turun untuk fail FBX.

    • Name
      obj
      Type
      string
      Description

      URL boleh dimuat turun untuk fail OBJ.

    • Name
      usdz
      Type
      string
      Description

      URL boleh dimuat turun untuk fail USDZ.

    • Name
      mtl
      Type
      string
      Description

      URL boleh dimuat turun untuk fail MTL, dikembalikan bersama eksport OBJ apabila tekstur hadir.

    • Name
      stl
      Type
      string
      Description

      URL boleh dimuat turun untuk fail STL.

    • Name
      3mf
      Type
      string
      Description

      URL boleh dimuat turun untuk fail 3MF. Hanya hadir apabila 3mf diminta melalui target_formats.

  • Name
    text_style_prompt
    Type
    string
    Description

    Ini ialah prompt teks yang digunakan untuk mencipta tugasan penteksturan.

  • Name
    image_style_url
    Type
    string
    Description

    Ini ialah input imej yang digunakan untuk mencipta tugasan penteksturan.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL boleh dimuat turun untuk imej kecil fail model.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL boleh dimuat turun untuk versi berlatar belakang lutsinar (RGBA) bagi thumbnail_url. Hanya hadir apabila tugasan dicipta dengan alpha_thumbnail: true dan pratonton lutsinar berjaya dirender; jika tidak, medan ini ditinggalkan.

  • Name
    progress
    Type
    integer
    Description

    Progress tugasan. Jika tugasan belum dimulakan, sifat ini akan menjadi 0. Setelah tugasan berjaya, ini akan menjadi 100.

  • Name
    started_at
    Type
    timestamp
    Description

    Cap masa apabila tugasan dimulakan, dalam milisaat. Jika tugasan belum dimulakan, sifat ini akan menjadi 0.

  • Name
    created_at
    Type
    timestamp
    Description

    Cap masa apabila tugasan dicipta, dalam milisaat.

  • Name
    expires_at
    Type
    timestamp
    Description

    Cap masa apabila hasil tugasan tamat tempoh, dalam milisaat.

  • Name
    finished_at
    Type
    timestamp
    Description

    Cap masa apabila tugasan disiapkan, dalam milisaat. Jika tugasan belum selesai, sifat ini akan menjadi 0.

  • Name
    status
    Type
    string
    Description

    Status tugasan. Nilai yang mungkin ialah salah satu daripada PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    texture_urls
    Type
    array
    Description

    Tatasusunan objek URL tekstur yang dijana daripada tugasan. Biasanya ini hanya mengandungi satu objek URL tekstur. Setiap URL tekstur mempunyai sifat berikut:

    • Name
      base_color
      Type
      string
      Description

      URL boleh dimuat turun untuk imej peta warna asas.

    • Name
      metallic
      Type
      string
      Description

      URL boleh dimuat turun untuk imej peta metalik.

    • Name
      normal
      Type
      string
      Description

      URL boleh dimuat turun untuk imej peta normal.

    • Name
      roughness
      Type
      string
      Description

      URL boleh dimuat turun untuk imej peta kekasaran.

    • Name
      emission
      Type
      string
      Description

      URL boleh dimuat turun untuk imej peta pancaran.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Bilangan tugasan terdahulu.

  • Name
    task_error
    Type
    object
    Description

    Butiran ralat untuk tugasan yang gagal. Lihat Ralat untuk rujukan objek task_error penuh.

  • Name
    consumed_credits
    Type
    integer
    Description

    Bilangan kredit yang digunakan oleh tugasan ini. Hadir apabila status tugasan ialah PENDING, IN_PROGRESS, atau SUCCEEDED. Mengembalikan 0 untuk tugasan FAILED (kredit dipulangkan semula apabila gagal).

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
}