API Reteksturowania

API Reteksturowania to funkcja, która pozwala zintegrować możliwości Reteksturowania AI Meshy z Twoją własną aplikacją. W tej sekcji znajdziesz wszystkie informacje potrzebne, aby rozpocząć korzystanie z tego API.


POST/openapi/v1/retexture

Utwórz zadanie Reteksturowania

Ten punkt końcowy umożliwia utworzenie nowego zadania Reteksturowania. Zobacz Obiekt zadania Reteksturowania, aby sprawdzić, które właściwości są zawarte w obiekcie zadania Reteksturowania.

Parametry

  • Name
    input_task_id
    Type
    string
    Wymagane
    Description

    ID ukończonego zadania Obraz na 3D lub Tekst na 3D, które chcesz reteksturować. To zadanie musi być jednym z następujących zadań: Text to 3D Preview, Text to 3D Refine, Obraz na 3D lub Remesh. Ponadto musi mieć status SUCCEEDED.

  • Name
    model_url
    Type
    string
    Wymagane
    Description

    Podaj model 3D dla Meshy do teksturowania. Obsługiwane formaty: .glb, .gltf, .obj, .fbx, .stl.

    Istnieją dwa sposoby podania modelu:

    • Publicznie dostępny URL: URL dostępny z publicznego internetu.
    • Data URI: Zakodowany w base64 Data URI modelu. Użyj MIME type application/octet-stream. Przykład: data:application/octet-stream;base64,<your base64-encoded model data>.
  • Name
    text_style_prompt
    Type
    string
    Wymagane
    Description

    Opisz pożądany styl tekstury obiektu za pomocą tekstu. Maksymalnie 600 znaków.

  • Name
    image_style_url
    Type
    string
    Wymagane
    Description

    Podaj obraz 2D, aby pokierować procesem teksturowania. Obecnie obsługujemy formaty .jpg, .jpeg i .png.

    Istnieją dwa sposoby podania obrazu:

    • Publicznie dostępny URL: URL dostępny z publicznego internetu
    • Data URI: Zakodowany w base64 Data URI obrazu. Przykład Data URI: data:image/jpeg;base64,<your base64-encoded image data>
  • Name
    ai_model
    Type
    string
    domyślne latest
    Description

    ID modelu AI do użycia przy reteksturowaniu. Dostępne wartości: meshy-5, meshy-6, latest (Meshy 6).

  • Name
    enable_original_uv
    Type
    boolean
    domyślne false
    Description

    Zachowuje istniejący układ UV modelu zamiast generowania nowego.

    • Jeśli reteksturowany model został wygenerowany przez Meshy (przez input_task_id lub model_url wskazujący na wynik Meshy), ustaw tę wartość na true, aby ponownie użyć jego zoptymalizowanego układu UV.
    • Jeśli reteksturujesz przesłany model innej firmy, ustaw true, gdy ma już dobre UV, które chcesz zachować, albo pozostaw false, aby pozwolić Meshy rozwinąć świeże UV (najlepsze dla modeli bez poprawnego mapowania UV).
  • Name
    enable_pbr
    Type
    boolean
    domyślne false
    Description

    Generuje mapy PBR (metallic, roughness, normal) oprócz koloru bazowego. Mapa emisji jest również dołączana, gdy ai_model to meshy-6 lub latest.

  • Name
    hd_texture
    Type
    boolean
    domyślne false
    Description

    Generuje teksturę koloru bazowego w rozdzielczości 4K (4096×4096), aby uzyskać więcej szczegółów.

  • Name
    remove_lighting
    Type
    boolean
    domyślne true
    Description

    Usuwa światła i cienie z tekstury koloru bazowego, tworząc czystszy wynik, który działa lepiej w niestandardowych konfiguracjach oświetlenia.

  • Name
    target_formats
    Type
    string[]
    Description

    Określa, które formaty plików 3D mają zostać uwzględnione w wyniku. Wygenerowane i zwrócone zostaną tylko żądane formaty, co może skrócić czas ukończenia zadania. W przypadku pominięcia uwzględniane są wszystkie obsługiwane formaty.

    Dostępne wartości: glb, obj, fbx, stl, usdz, 3mf

  • Name
    alpha_thumbnail
    Type
    boolean
    domyślne false
    Description

    Po ustawieniu na true zadanie dodatkowo renderuje wersję podglądu z przezroczystym tłem (RGBA) i zwraca ją jako alpha_thumbnail_url w odpowiedzi GET. Istniejące pole thumbnail_url pozostaje bez zmian.

Zwraca

Właściwość result odpowiedzi zawiera id zadania nowo utworzonego zadania Reteksturowania.

Tryby niepowodzenia

  • Name
    400 - Bad Request
    Description

    Żądanie było niedopuszczalne. Typowe przyczyny:

    • Brakujący parametr: Należy podać model_url albo input_task_id.
    • Brakujący styl: Należy podać text_style_prompt albo image_style_url.
    • Nieprawidłowe zadanie wejściowe: input_task_id musi odnosić się do pomyślnego zadania z obsługiwanego modelu.
    • Nieprawidłowy format modelu: model_url wskazuje plik z nieobsługiwanym rozszerzeniem.
    • Nieosiągalny URL: Nie można pobrać model_url lub image_style_url.
  • Name
    401 - Unauthorized
    Description

    Uwierzytelnianie nie powiodło się. Sprawdź swój klucz API.

  • Name
    402 - Payment Required
    Description

    Niewystarczająca liczba kredytów do wykonania tego zadania.

  • Name
    429 - Too Many Requests
    Description

    Przekroczono limit szybkości.

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

Pobierz zadanie Reteksturowanie

Ten punkt końcowy pozwala pobrać zadanie Reteksturowanie na podstawie prawidłowego id. Zapoznaj się z sekcją Obiekt zadania Reteksturowanie, aby zobaczyć, które właściwości są zawarte w obiekcie zadania Reteksturowanie.

Parametry

  • Name
    id
    Type
    path
    Description

    Unikalny identyfikator zadania Reteksturowanie do pobrania.

Zwraca

Odpowiedź zawiera obiekt zadania Reteksturowanie. Sprawdź sekcję Obiekt zadania Reteksturowanie, aby uzyskać szczegóły.

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

Usuń zadanie Reteksturowania

Ten punkt końcowy trwale usuwa zadanie reteksturowania, w tym wszystkie powiązane modele i dane. Ta czynność jest nieodwracalna.

Parametry ścieżki

  • Name
    id
    Type
    path
    Description

    Identyfikator zadania reteksturowania do usunięcia.

Zwraca

Zwraca 200 OK po powodzeniu.

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

Wyświetl listę zadań Reteksturowania

Ten punkt końcowy umożliwia pobranie listy zadań Reteksturowania.

Parametry

  • Name
    page_num
    Type
    integer
    domyślne 1
    Description

    Numer strony do stronicowania.

  • Name
    page_size
    Type
    integer
    domyślne 10
    Description

    Limit rozmiaru strony. Maksymalnie dozwolone jest 50 elementów.

  • Name
    sort_by
    Type
    string
    Description

    Pole, według którego sortować.

    Dostępne wartości:

    • +created_at: Sortuj według czasu utworzenia w kolejności rosnącej.
    • -created_at: Sortuj według czasu utworzenia w kolejności malejącej.

Zwraca

Zwraca stronicowaną listę Obiektów zadań Reteksturowania.

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

Strumieniuj zadanie Reteksturowania

Ten punkt końcowy strumieniuje aktualizacje w czasie rzeczywistym dla zadania Reteksturowania przy użyciu Server-Sent Events (SSE).

Parametry

  • Name
    id
    Type
    path
    Description

    Unikalny identyfikator zadania Reteksturowania do strumieniowania.

Zwraca

Zwraca strumień obiektów zadania Reteksturowania jako Server-Sent Events.

W przypadku zadań PENDING lub IN_PROGRESS strumień odpowiedzi będzie zawierać tylko niezbędne pola progress i 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
}

Obiekt zadania Reteksturowanie

Obiekt zadania Reteksturowanie to jednostka pracy, której Meshy używa do generowania tekstury 3D na podstawie danych wejściowych w postaci tekstu lub obrazu. Model ma następujące właściwości:

Properties

  • Name
    id
    Type
    string
    Description

    Unikalny identyfikator zadania. Chociaż jako szczegół implementacyjny używamy k-sortowalnego UUID dla identyfikatorów zadań, nie należy przyjmować żadnych założeń dotyczących formatu identyfikatora.

  • Name
    type
    Type
    string
    Description

    Typ zadania Reteksturowanie. Wartość to retexture.

  • Name
    model_urls
    Type
    object
    Description

    Adres URL do pobrania teksturowanego pliku modelu 3D wygenerowanego przez Meshy.

    • Name
      glb
      Type
      string
      Description

      Adres URL do pobrania pliku GLB.

    • Name
      fbx
      Type
      string
      Description

      Adres URL do pobrania pliku FBX.

    • Name
      obj
      Type
      string
      Description

      Adres URL do pobrania pliku OBJ.

    • Name
      usdz
      Type
      string
      Description

      Adres URL do pobrania pliku USDZ.

    • Name
      mtl
      Type
      string
      Description

      Adres URL do pobrania pliku MTL, zwracany wraz z eksportami OBJ, gdy obecne są tekstury.

    • Name
      stl
      Type
      string
      Description

      Adres URL do pobrania pliku STL.

    • Name
      3mf
      Type
      string
      Description

      Adres URL do pobrania pliku 3MF. Obecny tylko wtedy, gdy zażądano 3mf przez target_formats.

  • Name
    text_style_prompt
    Type
    string
    Description

    To jest prompt tekstowy, który został użyty do utworzenia zadania teksturowania.

  • Name
    image_style_url
    Type
    string
    Description

    To jest wejściowy obraz, który został użyty do utworzenia zadania teksturowania.

  • Name
    thumbnail_url
    Type
    string
    Description

    Adres URL do pobrania obrazu miniatury pliku modelu.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    Adres URL do pobrania wersji thumbnail_url z przezroczystym tłem (RGBA). Obecny tylko wtedy, gdy zadanie zostało utworzone z alpha_thumbnail: true i przezroczysty podgląd został pomyślnie wyrenderowany; w przeciwnym razie to pole jest pomijane.

  • Name
    progress
    Type
    integer
    Description

    Postęp zadania. Jeśli zadanie nie zostało jeszcze rozpoczęte, ta właściwość będzie mieć wartość 0. Gdy zadanie zakończy się powodzeniem, wartość zmieni się na 100.

  • Name
    started_at
    Type
    timestamp
    Description

    Znacznik czasu rozpoczęcia zadania, w milisekundach. Jeśli zadanie nie zostało jeszcze rozpoczęte, ta właściwość będzie mieć wartość 0.

  • Name
    created_at
    Type
    timestamp
    Description

    Znacznik czasu utworzenia zadania, w milisekundach.

  • Name
    expires_at
    Type
    timestamp
    Description

    Znacznik czasu wygaśnięcia wyniku zadania, w milisekundach.

  • Name
    finished_at
    Type
    timestamp
    Description

    Znacznik czasu zakończenia zadania, w milisekundach. Jeśli zadanie nie zostało jeszcze zakończone, ta właściwość będzie mieć wartość 0.

  • Name
    status
    Type
    string
    Description

    Status zadania. Możliwe wartości to jedna z: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    texture_urls
    Type
    array
    Description

    Tablica obiektów URL tekstur, które są generowane z zadania. Zwykle zawiera tylko jeden obiekt URL tekstury. Każdy URL tekstury ma następujące właściwości:

    • Name
      base_color
      Type
      string
      Description

      Adres URL do pobrania obrazu mapy koloru bazowego.

    • Name
      metallic
      Type
      string
      Description

      Adres URL do pobrania obrazu mapy metaliczności.

    • Name
      normal
      Type
      string
      Description

      Adres URL do pobrania obrazu mapy normalnych.

    • Name
      roughness
      Type
      string
      Description

      Adres URL do pobrania obrazu mapy chropowatości.

    • Name
      emission
      Type
      string
      Description

      Adres URL do pobrania obrazu mapy emisji.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Liczba poprzedzających zadań.

  • Name
    task_error
    Type
    object
    Description

    Szczegóły błędu dla zadań zakończonych niepowodzeniem. Zobacz Błędy, aby uzyskać pełną referencję obiektu task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Liczba kredytów zużytych przez to zadanie. Obecna, gdy status zadania to PENDING, IN_PROGRESS lub SUCCEEDED. Zwraca 0 dla zadań FAILED (kredyty są zwracane w przypadku niepowodzenia).

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
}