Creative Lab — Schlüsselanhänger-API

Verwandeln Sie ein Ausgangsfoto in zwei Schritten in ein 3D-druckbares Schlüsselanhänger-Medaillon — ein abzeichenförmiges, farbiges Tiefenrelief: prototype erzeugt aus Ihrem Eingabefoto ein farbiges Konzeptbild, und build verwandelt dieses Konzeptbild anschließend in ein reliefartiges 3D-Modell. Die beiden Schritte sind über input_task_id miteinander verknüpft.

POST /openapi/creative-lab/keychain/v1/prototype
POST /openapi/creative-lab/keychain/v1/build

POST/openapi/creative-lab/keychain/v1/prototype

Erstellen einer Keychain-Prototyp-Aufgabe

Generiert ein einzelnes koloriertes Konzeptbild aus dem Quellfoto. Die zurückgegebene Task-ID wird als input_task_id an den Build-Endpunkt übergeben. Die Antwortstruktur ist unter Das Keychain-Prototyp-Task-Objekt beschrieben.

Parameter

Name
image_url
Type
string
Erforderlich
Description
Quellfoto, das Meshy zu einem für den Keychain-Druck vorbereiteten kolorierten Konzeptbild umwandeln soll. Derzeit werden die Formate .jpg, .jpeg, .png und .webp unterstützt.
Es gibt zwei Möglichkeiten, das Bild bereitzustellen:
- Öffentlich zugängliche URL: Eine URL, die aus dem öffentlichen Internet erreichbar ist.
- Data URI: Eine base64-kodierte Data URI des Bildes. Beispiel für eine Data URI: data:image/jpeg;base64,<Ihre base64-kodierten Bilddaten>.
Name
name
Type
string
Description
Optionaler Aufgabenname für Anzeigezwecke. Maximal 100 Zeichen.
Dieser Name kennzeichnet die Aufgabe in Ihrem Dashboard und in Aufgabenlisten. Er wird nicht auf den Schlüsselanhänger graviert — verwenden Sie dafür name_text.
Name
name_text
Type
string
Description
Text, der auf den Schlüsselanhänger graviert werden soll, z. B. der Name eines Haustiers oder einer Person. Maximal 10 Zeichen, gezählt als Unicode-Zeichen und nicht als Bytes, sodass auch ein 10 Zeichen langer chinesischer, japanischer oder koreanischer Name akzeptiert wird. Lassen Sie das Feld leer, um einen Schlüsselanhänger ohne Gravur zu erzeugen.
Umgebende Leerzeichen werden entfernt und unsichtbare Formatierungszeichen werden vor der Verwendung des Textes entfernt. Der resultierende Wert wird als name_text im Prototyp-Task-Objekt zurückgegeben, sodass Sie genau bestätigen können, was graviert wird, bevor Sie für die Build-Phase bezahlen.
Die Gravur wird hier, in der Prototyp-Phase, angewendet. Die Build-Phase übernimmt sie automatisch und akzeptiert kein eigenes name_text.
Wenn der Text nicht aus reinem ASCII besteht, senden Sie den Request-Body als UTF-8 und setzen Sie Content-Type: application/json; charset=utf-8. Einige HTTP-Clients — darunter das Invoke-RestMethod von Windows PowerShell — kodieren den Body standardmäßig als ISO-8859-1, wodurch jedes nicht-lateinische Zeichen stillschweigend in ? umgewandelt wird, bevor es Meshy erreicht. Die API kann dies nicht von einer tatsächlich gewünschten Gravur unterscheiden.
Name
remove_background
Type
boolean
Standard false
Description
Wenn auf true gesetzt, wird das Prototypbild als transparentes RGBA-PNG mit entferntem Hintergrund zurückgegeben, sodass Sie das Motiv auf einen beliebigen Hintergrund einfügen können.
Dies steuert nur das von diesem Endpunkt zurückgegebene Bild. Es ist unabhängig von der gleichnamigen Build-Option (Standardwert true), die die Hintergrundentfernung vor dem Reliefing steuert.

Rückgabewerte

Die Eigenschaft result der Antwort enthält die Task-id der neu erstellten Keychain-Prototyp-Aufgabe. Fragen Sie den Get a Task-Endpunkt ab oder abonnieren Sie den Stream, bis die Aufgabe den Status SUCCEEDED erreicht, und übergeben Sie diese ID dann als input_task_id an den Build-Endpunkt.

Fehlerfälle

Name
400 - Bad Request
Description
Die Anfrage war ungültig. Häufige Ursachen:
- Fehlender Parameter: image_url ist erforderlich.
- Ungültiges Bildformat: Die angegebene image_url hat kein unterstütztes Format (.jpg, .jpeg, .png, .webp).
- Bildabmessungen außerhalb des zulässigen Bereichs: Das Bild ist zu klein, überschreitet die maximale Dateigröße oder überschreitet die maximale Pixelanzahl.
- Nicht erreichbare URL: Die image_url konnte nicht heruntergeladen werden (404 oder Timeout).
- Ungültige Data URI: Der base64-String ist fehlerhaft.
- Gravur zu lang: name_text ist länger als 10 Zeichen. Die Anfrage wird abgelehnt statt gekürzt, sodass Ihnen niemals ein Schlüsselanhänger mit gekürztem Namen berechnet wird.
- Inhalt markiert: Das Eingabebild wurde durch die NSFW- oder Urheberrechts-moderation markiert, oder die name_text-Gravur wurde durch die NSFW-moderation markiert. Die Gravur wird nur auf NSFW-Inhalte geprüft — die Prüfung auf geistiges Eigentum betrifft nur das Bild.
Name
401 - Unauthorized
Description
Die Authentifizierung ist fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.
Name
402 - Payment Required
Description
Unzureichende Credits, um diese Aufgabe auszuführen.
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten.

Request

POST

/openapi/creative-lab/keychain/v1/prototype

# Stage 1: generate a colorized keychain concept image
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>",
    "name_text": "Luna"
  }'

Response

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

Prototyp-Beispiel

Beginnen Sie mit einem Quellfoto und erzeugen Sie anschließend das Prototypbild, das von der Keychain-Build-Phase verwendet wird.

Quellfoto, das als Eingabe für Creative Lab Keychain verwendet wird — Prototyp-Eingabe

Aus dem Quellfoto erzeugte Creative Lab Keychain Prototyp-Ausgabe — Prototyp-Ausgabe

POST/openapi/creative-lab/keychain/v1/build

Create a Keychain Build Task

Erzeugt das finale, 3D-druckbare Keychain-Medaillon aus einer erfolgreich abgeschlossenen Prototyp-Aufgabe. Der Build führt eine Tiefenkarten-Relief-Pipeline auf dem kolorierten Konzeptbild des Prototyps aus und liefert ein einzelnes Netz-Artefakt im gewünschten Format. Die Form der Antwort finden Sie unter Das Keychain-Build-Task-Objekt.

Parameter

Name
input_task_id
Type
string
Erforderlich
Description
Die Task-ID einer Prototyp-Aufgabe, die über denselben OpenAPI-Endpunkt erstellt wurde. Der Prototyp muss mit demselben API-Schlüssel erstellt worden sein, muss SUCCEEDED erreicht haben und genau ein Kandidatenbild erzeugt haben.
Über die Webapp erstellte Prototyp-Aufgaben werden nicht akzeptiert – der Build-Endpunkt akzeptiert ausschließlich Prototyp-Aufgaben, die über POST /openapi/creative-lab/keychain/v1/prototype erzeugt wurden, und lehnt jede andere Quelle mit 404 ab.
Name
name
Type
string
Description
Optionaler Task-Name zu Anzeigezwecken. Maximal 100 Zeichen.

`options`

Optionale Feinabstimmungsparameter für die Relief-Geometrie. Jedes Feld hat einen sinnvollen Standardwert – senden Sie nur die Felder, die Sie überschreiben möchten.

Name
badge_shape
Type
string
Standard circle
Description
Umriss-Silhouette des Keychain-Medaillons. Verfügbare Werte:
- circle (Standard)
- rounded-rect
- hexagon
- shield
- star
Name
size_mm
Type
number
Standard 40
Description
Kantenlänge des umgebenden Quadrats des Keychains, in Millimetern. Bereich: (0, 400].
Name
relief_height_mm
Type
number
Standard 2.2
Description
Maximale Reliefhöhe über der Basis, in Millimetern. Bereich: [0, 20].
Name
relief_offset_mm
Type
number
Standard 0
Description
Vertikaler Versatz, der vor der Extrusion auf das Relief angewendet wird, in Millimetern. Bereich: [0, 20].
Name
base_thickness_mm
Type
number
Standard 0.1
Description
Dicke der flachen Grundplatte hinter dem Relief, in Millimetern. Bereich: [0, 20].
Name
has_closed_back
Type
boolean
Standard true
Description
Ob die Rückseite des Medaillons als geschlossene Fläche versiegelt ist. Auf false setzen für eine offene Schale.
Name
relief_curve
Type
string
Standard linear
Description
Übertragungskurve, die Tiefenkartenwerte auf die Reliefhöhe abbildet. Verfügbare Werte:
- linear (Standard)
- gamma
- s-curve
Name
curve_param
Type
number
Standard 1.0
Description
Formparameter für die Übertragungskurve (nur relevant, wenn relief_curve gleich gamma ist). Bereich: (0, 10].
Name
invert_depth
Type
boolean
Standard false
Description
Kehrt die Interpretation der Tiefenkarte um, sodass dunklere Bereiche zu höherem Relief werden.
Name
smoothing
Type
number
Standard 0.24
Description
Glättungsstärke, die vor der Reliefextraktion auf die Tiefenkarte angewendet wird. Bereich: [0, 10].
Name
relief_scale
Type
number
Standard 1.0
Description
Vertikaler Skalierungsfaktor, der zusätzlich zu relief_height_mm angewendet wird. Bereich: (0, 10].
Name
depth_threshold
Type
number
Standard 0.1
Description
Tiefpass-Schwellenwert für Tiefenkartenwerte; alles darunter wird auf null begrenzt. Bereich: [0, 1].
Name
remove_background
Type
boolean
Standard true
Description
Entfernt automatisch den Hintergrund des Konzeptbilds des Prototyps vor der Reliefierung.
Unabhängig vom gleichnamigen Prototyp-Parameter (Standard false), der steuert, ob das Prototypbild selbst mit Transparenz zurückgegeben wird.
Name
export_resolution
Type
integer
Standard 512
Description
Für den Export verwendete Netzauflösung. Bereich: [64, 2048].

`output`

Optionaler Auswahlparameter für das Übertragungsformat. Standardwert ist glb.

Name
format
Type
string
Standard glb
Description
Artefakt-Bündel, das vom Build zurückgegeben wird. Verfügbare Werte:
- glb (Standard) — liefert eine einzelne model.glb unter model_urls.glb.
- obj — packt model.obj + model.mtl + texture.png in ein Zip-Archiv und liefert das Bündel unter model_urls.obj.
- zip — packt jedes vom Generator erzeugte Artefakt in ein Zip-Archiv und liefert das Bündel unter model_urls.bundle_zip.

Rückgabewerte

Die result-Eigenschaft der Antwort enthält die Task-id der neu erstellten Keychain-Build-Aufgabe. Fragen Sie den Get a Task-Endpunkt ab oder abonnieren Sie den Stream, bis die Aufgabe SUCCEEDED erreicht, und laden Sie dann das Artefakt aus dem einzigen Eintrag in model_urls herunter.

Fehlermodi

Name
400 - Bad Request
Description
Die Anfrage war nicht akzeptabel. Häufige Ursachen:
- Fehlender Parameter: input_task_id ist erforderlich.
- Ungültige UUID: input_task_id ist keine gültige UUID.
- Übergeordnete Aufgabe nicht erfolgreich: Die referenzierte Prototyp-Aufgabe hat SUCCEEDED noch nicht erreicht.
- Kein Kandidat: Die Prototyp-Aufgabe war erfolgreich, hat aber kein Kandidatenbild erzeugt.
- Optionen außerhalb des Bereichs: Eines der options-Felder lag außerhalb des zulässigen Bereichs oder Enum-Werte.
Name
401 - Unauthorized
Description
Authentifizierung fehlgeschlagen. Bitte überprüfen Sie Ihren API-Schlüssel.
Name
402 - Payment Required
Description
Nicht genügend Credits, um diese Aufgabe auszuführen.
Name
404 - Not Found
Description
Die referenzierte Prototyp-Aufgabe existiert nicht, gehört einem anderen Benutzer oder wurde über die Webapp erstellt (nur Prototyp-Aufgaben im API-Modus können in einen Build übergehen).
Name
429 - Too Many Requests
Description
Sie haben Ihre Ratenbegrenzung überschritten.

Request

POST

/openapi/creative-lab/keychain/v1/build

# Stage 2: chain build off a succeeded prototype task
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build \
  -X POST \
  -H "Authorization: Bearer ${YOUR_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "input_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "options": {
      "badge_shape": "circle",
      "size_mm": 40,
      "relief_height_mm": 2.5
    },
    "output": {
      "format": "glb"
    }
  }'

Response

{
  "result": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb"
}

Build example

Die Build-Aufgabe wandelt das ausgewählte Prototypbild in ein 3D-druckbares Keychain-Modell um.

Creative Lab Keychain build model preview — Build model preview

GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Einen Schlüsselanhänger-Task abrufen

Ruft einen Prototyp- oder Build-Task anhand einer gültigen Task-id ab. Der URL-Pfad muss mit der Stufe des Tasks übereinstimmen — ein Build-Task, der über /prototype/:id abgerufen wird, liefert 404, und umgekehrt.

Siehe Das Keychain-Prototype-Task-Objekt und Das Keychain-Build-Task-Objekt für die Struktur der Antworten.

Parameter

Name
id
Type
path
Description
Eindeutige Kennung für den abzurufenden Schlüsselanhänger-Task.

Rückgabewerte

Die Antwort enthält das Schlüsselanhänger-Task-Objekt. Die Struktur hängt davon ab, welche Stufe angefordert wurde.

Request

GET

/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

# Prototype
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# Build
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Prototype Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Build Response

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

DELETE/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Eine Keychain-Aufgabe löschen

Bricht eine Keychain-Aufgabe ab. Wenn sich die Aufgabe noch im Status PENDING befindet, werden die bei der Erstellung verbrauchten Credits erstattet. Aufgaben, die sich bereits IN_PROGRESS befinden, werden ohne Erstattung abgebrochen (der Worker verbraucht möglicherweise bereits Ressourcen). Aufgaben, die bereits einen Endzustand erreicht haben (SUCCEEDED, FAILED, CANCELED), können nicht abgebrochen werden.

Der URL-Pfad muss der Phase der Aufgabe entsprechen — ein DELETE auf /prototype/:buildId liefert 404.

Pfadparameter

Name
id
Type
path
Description
Eindeutige Kennung der abzubrechenden Keychain-Aufgabe.

Rückgabewerte

Gibt bei Erfolg 204 No Content mit leerem Textkörper zurück.

Fehlermodi

Name
400 - Bad Request
Description
Die Aufgabe befindet sich bereits in einem Endzustand und kann nicht abgebrochen werden.
Name
404 - Not Found
Description
Die Aufgabe existiert nicht, gehört einem anderen Benutzer, oder ihre Phase stimmt nicht mit dem URL-Pfad überein.

Request

DELETE

/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578

curl --request DELETE \
  --url https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Returns 204 No Content on success (empty body).

GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id/stream

Stream a Keychain Task

Streamt Echtzeit-Updates für einen Keychain-Task über Server-Sent Events (SSE). Der URL-Pfad muss zur Stufe des Tasks passen — wird ein Stream unter /prototype/:buildId/stream geöffnet, wird ein einzelnes event: error-Payload mit status_code: 404 gesendet, und der Stream wird geschlossen.

Parameter

Name
id
Type
path
Description
Eindeutige Kennung des zu streamenden Keychain-Tasks.

Rückgabe

Gibt einen Stream von Keychain Prototype- oder Keychain Build-Task-Objekten als Server-Sent Events zurück. Jeder Frame enthält das vollständige Task-Objekt für die jeweilige Stufe — dieselbe Struktur, die der Get-Endpunkt zurückgibt — solange der Task also PENDING oder IN_PROGRESS ist, sind die Ausgabefelder einfach noch nicht befüllt (null, [] oder {}), und finished_at ist null.

Request

GET

/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream

curl -N https://api.meshy.ai/openapi/creative-lab/keychain/v1/build/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Error event example (wrong stage or task not found)
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// Every frame is the full task object; fields not yet populated are null / empty.
// The PENDING frame below is abbreviated to the fields that change.
event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}

GET/openapi/creative-lab/keychain/v1/(prototype|build)

List Keychain Tasks

Ruft eine paginierte Liste Ihrer Schlüsselanhänger-Tasks für eine einzelne Stufe ab. Der URL- Pfad wählt die Stufe aus — /prototype liefert Prototyp-Tasks; /build liefert Build-Tasks. Tasks der jeweils anderen Stufe sind in keiner der beiden Antworten enthalten.

Path-Parameter

Name
stage
Type
path
Erforderlich
Description
Entweder prototype oder build. Die Sammlung liefert nur Tasks zurück, deren Stufe mit der URL übereinstimmt — ein Abruf von /prototype liefert niemals Build-Tasks und umgekehrt.

Query-Parameter

Name
page_num
Type
integer
Standard 1
Description
Seitennummer für die Paginierung.
Name
page_size
Type
integer
Standard 10
Description
Seitengrößenlimit. Maximal zulässig sind 100 Einträge.
Name
sort_by
Type
string
Standard -created_at
Description
Feld, nach dem sortiert werden soll. Verfügbare Werte:
- +created_at: Sortierung nach Erstellungszeit in aufsteigender Reihenfolge.
- -created_at: Sortierung nach Erstellungszeit in absteigender Reihenfolge.

Rückgabewerte

Gibt eine paginierte Liste des stufenspezifischen Task-Objekts zurück — entweder das Keychain-Prototyp-Task-Objekt beim Auflisten von /prototype oder das Keychain-Build-Task-Objekt beim Auflisten von /build.

Request

GET

/openapi/creative-lab/keychain/v1/prototype

# List prototype tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/prototype?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

# List build tasks
curl https://api.meshy.ai/openapi/creative-lab/keychain/v1/build?page_size=10 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response (List Prototype Tasks)

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "creative-lab-keychain-prototype",
    "name": "",
    "status": "SUCCEEDED",
    "progress": 100,
    "created_at": 1729123456000,
    "started_at": 1729123460000,
    "finished_at": 1729123486000,
    "expires_at": 1729382686000,
    "preceding_tasks": 0,
    "task_error": null,
    "consumed_credits": 6,
    "image_urls": [
      "https://assets.meshy.ai/***/concept.png?Expires=***"
    ]
  }
]

The Keychain Prototype Task Object

Das Keychain-Prototype-Task-Objekt ist eine Arbeitseinheit, die Meshy verfolgt, um aus einem Quellfoto ein koloriertes Konzeptbild zu erzeugen. Die Ausgabe dieser Stufe wird über input_task_id mit der Build-Stufe verkettet.

Eigenschaften

Name
id
Type
string
Description
Eindeutige Kennung für die Aufgabe. Auch wenn wir als Implementierungsdetail eine k-sortierbare UUID für Task-IDs verwenden, solltest du keine Annahmen über das Format der ID treffen.
Name
type
Type
string
Description
Typ der Aufgabe. Der Wert ist creative-lab-keychain-prototype.
Name
name
Type
string
Description
Der beim Erstellen der Aufgabe angegebene Aufgabenname. Leerer String, wenn kein Name angegeben wurde.
Name
name_text
Type
string
Description
Die für diesen Schlüsselanhänger vorgesehene Gravur, nach dem Entfernen von Leerzeichen am Anfang/Ende und unsichtbaren Formatierungszeichen. Nicht vorhanden, wenn die Aufgabe ohne name_text erstellt wurde. Vergleiche sie mit dem, was du gesendet hast, um sicherzustellen, dass der Text die Kodierung deines HTTP-Clients unbeschadet überstanden hat.
Name
status
Type
string
Description
Status der Aufgabe. Mögliche Werte sind einer von PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Fortschritt der Aufgabe. Wenn die Aufgabe noch nicht gestartet wurde, ist diese Eigenschaft 0. Sobald die Aufgabe erfolgreich abgeschlossen wurde, wird sie zu 100.
Name
created_at
Type
timestamp
Description
Zeitstempel der Erstellung der Aufgabe, in Millisekunden.
Ein Zeitstempel repräsentiert die Anzahl der seit dem 1. Januar 1970 UTC vergangenen Millisekunden, gemäß dem Standard RFC 3339. Zum Beispiel wird Freitag, der 1. September 2023, 12:00:00 Uhr GMT als 1693569600000 dargestellt. Dies gilt für alle Zeitstempel in der Meshy API.
Name
started_at
Type
timestamp
Description
Zeitstempel des Starts der Aufgabe, in Millisekunden. Wenn die Aufgabe noch nicht gestartet wurde, ist diese Eigenschaft 0.
Name
finished_at
Type
timestamp
Description
Zeitstempel des Abschlusses der Aufgabe, in Millisekunden. Wenn die Aufgabe noch nicht abgeschlossen wurde, ist diese Eigenschaft 0.
Name
expires_at
Type
timestamp
Description
Zeitstempel des Ablaufs des Aufgabenergebnisses, in Millisekunden.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorausgehenden Aufgaben.
Der Wert dieses Felds ist nur dann aussagekräftig, wenn der Aufgabenstatus PENDING ist.
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Aufgaben. Siehe Fehler für die vollständige Referenz zum task_error-Objekt.
Name
consumed_credits
Type
integer
Description
Die Anzahl der von dieser Aufgabe verbrauchten Credits. Vorhanden, wenn der Aufgabenstatus PENDING, IN_PROGRESS oder SUCCEEDED ist. Gibt für FAILED-Aufgaben 0 zurück (Credits werden bei einem Fehlschlag erstattet).
Name
image_urls
Type
array of strings
Description
Herunterladbare URLs für die von dieser Prototype-Aufgabe generierten Konzeptbild-Kandidaten. Aktuell liefert die API immer genau einen Kandidaten zurück; das Feld ist ein Array, damit zukünftige Überarbeitungen mehrere Kandidaten ohne Breaking Change bereitstellen können.

Example Keychain Prototype Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "creative-lab-keychain-prototype",
  "name": "",
  "name_text": "Luna",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123456000,
  "started_at": 1729123460000,
  "finished_at": 1729123486000,
  "expires_at": 1729382686000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 6,
  "image_urls": [
    "https://assets.meshy.ai/***/concept.png?Expires=***"
  ]
}

Das Keychain-Build-Task-Objekt

Das Keychain-Build-Task-Objekt ist eine Arbeitseinheit, die Meshy verfolgt, um aus einem erfolgreichen Prototyp-Task das finale 3D-Schlüsselanhänger-Netz zu erzeugen. Der Build führt eine Tiefenkarten-Relief-Pipeline auf dem Konzeptbild des Prototyps aus und veröffentlicht ein einzelnes Netz-Artefakt in dem vom Aufrufer angeforderten Format.

Eigenschaften

Name
id
Type
string
Description
Eindeutige Kennung für den Task.
Name
type
Type
string
Description
Typ des Tasks. Der Wert ist creative-lab-keychain-build.
Name
name
Type
string
Description
Der beim Erstellen des Tasks angegebene Task-Name. Leerer String, wenn kein Name angegeben wurde.
Name
status
Type
string
Description
Status des Tasks. Mögliche Werte sind PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.
Name
progress
Type
integer
Description
Fortschritt des Tasks. Wenn der Task noch nicht gestartet wurde, ist diese Eigenschaft 0. Sobald der Task erfolgreich abgeschlossen wurde, wird sie 100.
Name
created_at
Type
timestamp
Description
Zeitstempel der Erstellung des Tasks, in Millisekunden.
Name
started_at
Type
timestamp
Description
Zeitstempel des Starts des Tasks, in Millisekunden.
Name
finished_at
Type
timestamp
Description
Zeitstempel des Abschlusses des Tasks, in Millisekunden.
Name
expires_at
Type
timestamp
Description
Zeitstempel, wann das Ergebnis des Tasks abläuft, in Millisekunden.
Name
preceding_tasks
Type
integer
Description
Die Anzahl der vorausgehenden Tasks. Nur relevant, wenn der Status PENDING ist.
Name
task_error
Type
object
Description
Fehlerdetails für fehlgeschlagene Tasks. Siehe Fehler für die vollständige Referenz des task_error-Objekts.
Name
consumed_credits
Type
integer
Description
Die Anzahl der von diesem Task verbrauchten Credits. Gibt 0 für FAILED-Tasks zurück (Credits werden bei einem Fehlschlag zurückerstattet).
Name
model_urls
Type
object
Description
Herunterladbare URLs für das generierte Artefakt, indiziert nach Artefaktname. Enthält immer genau einen Eintrag — das über output.format der Build-Anfrage angeforderte Format. Der Schlüssel entspricht dem angeforderten Format:
- Name
  glb
  Type
  string
  Description
  Herunterladbare URL zur GLB-Datei. Vorhanden, wenn output.format auf glb gesetzt war (Standard).
- Name
  obj
  Type
  string
  Description
  Herunterladbare URL zu einem Zip-Bundle, das model.obj, model.mtl und texture.png enthält. Vorhanden, wenn output.format auf obj gesetzt war.
- Name
  bundle_zip
  Type
  string
  Description
  Herunterladbare URL zu einem Zip-Bundle sämtlicher vom Generator erzeugten Artefakte. Vorhanden, wenn output.format auf zip gesetzt war.

Example Keychain Build Task Object

{
  "id": "019c320e-9a8f-7a1c-9c11-2a1876f8a9bb",
  "type": "creative-lab-keychain-build",
  "name": "",
  "status": "SUCCEEDED",
  "progress": 100,
  "created_at": 1729123500000,
  "started_at": 1729123510000,
  "finished_at": 1729123535000,
  "expires_at": 1729382735000,
  "preceding_tasks": 0,
  "task_error": null,
  "consumed_credits": 20,
  "model_urls": {
    "glb": "https://assets.meshy.ai/***/tasks/019c320e-9a8f-7a1c-9c11-2a1876f8a9bb/output/model.glb?Expires=***"
  }
}