Creative Lab — API брелока

Превратите исходную фотографию в медальон-брелок, пригодный для 3D-печати, — цветной рельеф в форме значка — в два этапа: prototype создаёт цветное концептуальное изображение на основе вашей входной фотографии, а затем build превращает это концептуальное изображение в рельефную 3D-модель. Оба этапа связаны через input_task_id.

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

Создание задачи прототипа брелка

Сгенерируйте единое цветное концептуальное изображение из исходной фотографии. Возвращённый ID задачи — это то, что вы передаёте как input_task_id в эндпоинт сборки. Обратитесь к разделу Объект задачи прототипа брелка для описания структуры ответа.

Параметры

  • Name
    image_url
    Type
    string
    Обязательный
    Description

    Исходная фотография, которую Meshy преобразует в цветное концептуальное изображение, готовое для брелка. В настоящее время поддерживаются форматы .jpg, .jpeg, .png и .webp.

    Изображение можно предоставить двумя способами:

    • Публично доступный URL: URL, доступный из публичного интернета.
    • Data URI: изображение, закодированное в base64 в виде data URI. Пример data URI: data:image/jpeg;base64,<ваши закодированные в base64 данные изображения>.
  • Name
    name
    Type
    string
    Description

    Необязательное название задачи для отображения. Максимум 100 символов.

    Это название отображается в вашей панели управления и списках задач. Оно не гравируется на брелке — для этого используйте name_text.

  • Name
    name_text
    Type
    string
    Description

    Текст для гравировки на брелке, например имя питомца или человека. Максимум 10 символов, считаются как символы Unicode, а не байты, поэтому принимается 10-символьное имя на китайском, японском или корейском языке. Оставьте это поле пустым, чтобы получить брелок без гравировки.

    Перед использованием текста удаляются пробелы по краям и невидимые форматирующие символы. Итоговое значение возвращается как name_text в объекте задачи прототипа, так что вы можете подтвердить, что именно будет выгравировано, ещё до оплаты этапа сборки.

    Гравировка применяется именно на этапе прототипа. Этап сборки автоматически наследует её и не принимает собственный параметр name_text.

    Если текст содержит символы, отличные от ASCII, отправляйте тело запроса в кодировке UTF-8 и указывайте Content-Type: application/json; charset=utf-8. Некоторые HTTP-клиенты — в том числе Invoke-RestMethod в Windows PowerShell — по умолчанию кодируют тело в ISO-8859-1, что незаметно превращает каждый нелатинский символ в ? ещё до того, как запрос дойдёт до Meshy. API не может отличить это от гравировки, которую вы действительно запросили.

  • Name
    remove_background
    Type
    boolean
    по умолчанию false
    Description

    При значении true изображение прототипа возвращается в виде прозрачного PNG в формате RGBA с удалённым фоном, чтобы вы могли разместить объект на любом фоне.

    Этот параметр управляет только изображением, которое возвращает данный эндпоинт. Он не связан с одноимённым параметром сборки (значение по умолчанию true), который управляет удалением фона перед созданием рельефа.

Возвращаемые данные

Свойство result ответа содержит id задачи только что созданного прототипа брелка. Опрашивайте эндпоинт Получение задачи или подпишитесь на поток, пока задача не достигнет статуса SUCCEEDED, затем передайте этот ID в эндпоинт сборки как input_task_id.

Режимы отказа

  • Name
    400 - Bad Request
    Description

    Запрос был некорректен. Распространённые причины:

    • Отсутствует параметр: image_url обязателен.
    • Неверный формат изображения: указанный image_url имеет неподдерживаемый формат (.jpg, .jpeg, .png, .webp).
    • Размеры изображения вне допустимого диапазона: изображение слишком маленькое, превышает максимальный размер файла или максимальное количество пикселей.
    • Недоступный URL: не удалось загрузить image_url (404 или timeout).
    • Некорректный Data URI: строка base64 имеет неверный формат.
    • Слишком длинная гравировка: name_text превышает 10 символов. Запрос отклоняется, а не обрезается, поэтому с вас никогда не спишут кредиты за брелок с гравировкой сокращённого имени.
    • Контент помечен модерацией: исходное изображение было помечено модерацией NSFW или на предмет нарушения прав интеллектуальной собственности, либо гравировка name_text была помечена модерацией NSFW. Гравировка проверяется только на предмет NSFW-контента — проверка на нарушение прав интеллектуальной собственности применяется к изображению.
  • Name
    401 - Unauthorized
    Description

    Ошибка аутентификации. Проверьте ваш API-ключ.

  • Name
    402 - Payment Required
    Description

    Недостаточно кредитов для выполнения этой задачи.

  • Name
    429 - Too Many Requests
    Description

    Вы превысили ограничение частоты запросов.

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"
}
Prototype example
Start with a source photo, then generate the prototype image used by the keychain build stage.
Source photo used as the Creative Lab Keychain input
Prototype input
Creative Lab Keychain prototype output generated from the source photo
Prototype output
POST/openapi/creative-lab/keychain/v1/build

Создание задачи сборки брелока

Создает финальную 3D-печатную медальон-брелок на основе успешно выполненной задачи прототипа. Сборка запускает конвейер рельефа по карте глубины на основе цветного концептуального изображения прототипа и создает единый артефакт сетки в запрошенном формате. Информацию о структуре ответа см. в разделе Объект задачи сборки брелока.

Параметры

  • Name
    input_task_id
    Type
    string
    Обязательный
    Description

    ID задачи прототипа, созданной через этот же эндпоинт OpenAPI. Прототип должен быть создан с тем же API-ключом, должен достичь статуса SUCCEEDED и должен был сгенерировать ровно одно изображение-кандидат.

    Задачи прототипов, созданные через веб-приложение, не принимаются — эндпоинт сборки принимает только задачи прототипов, созданные через POST /openapi/creative-lab/keychain/v1/prototype, и отклоняет любой другой источник с ошибкой 404.

  • Name
    name
    Type
    string
    Description

    Необязательное название задачи для отображения. Максимум 100 символов.

options

Необязательные параметры настройки геометрии рельефа. Для каждого поля предусмотрено разумное значение по умолчанию — отправляйте только те, которые нужно переопределить.

  • Name
    badge_shape
    Type
    string
    по умолчанию circle
    Description

    Контурный силуэт медальона-брелока. Доступные значения:

    • circle (по умолчанию)
    • rounded-rect
    • hexagon
    • shield
    • star
  • Name
    size_mm
    Type
    number
    по умолчанию 40
    Description

    Длина стороны ограничивающего квадрата брелока в миллиметрах. Диапазон: (0, 400].

  • Name
    relief_height_mm
    Type
    number
    по умолчанию 2.2
    Description

    Максимальная высота рельефа над основанием в миллиметрах. Диапазон: [0, 20].

  • Name
    relief_offset_mm
    Type
    number
    по умолчанию 0
    Description

    Вертикальное смещение, применяемое к рельефу перед экструзией, в миллиметрах. Диапазон: [0, 20].

  • Name
    base_thickness_mm
    Type
    number
    по умолчанию 0.1
    Description

    Толщина плоской базовой пластины позади рельефа, в миллиметрах. Диапазон: [0, 20].

  • Name
    has_closed_back
    Type
    boolean
    по умолчанию true
    Description

    Определяет, запечатана ли задняя сторона медальона в виде закрытой поверхности. Установите false для открытой оболочки.

  • Name
    relief_curve
    Type
    string
    по умолчанию linear
    Description

    Передаточная кривая, отображающая значения карты глубины в высоту рельефа. Доступные значения:

    • linear (по умолчанию)
    • gamma
    • s-curve
  • Name
    curve_param
    Type
    number
    по умолчанию 1.0
    Description

    Параметр формы для передаточной кривой (имеет значение только при relief_curve, равном gamma). Диапазон: (0, 10].

  • Name
    invert_depth
    Type
    boolean
    по умолчанию false
    Description

    Инвертирует интерпретацию карты глубины, чтобы более тёмные области становились более высоким рельефом.

  • Name
    smoothing
    Type
    number
    по умолчанию 0.24
    Description

    Сила сглаживания, применяемая к карте глубины перед извлечением рельефа. Диапазон: [0, 10].

  • Name
    relief_scale
    Type
    number
    по умолчанию 1.0
    Description

    Множитель вертикального масштаба, применяемый поверх relief_height_mm. Диапазон: (0, 10].

  • Name
    depth_threshold
    Type
    number
    по умолчанию 0.1
    Description

    Порог нижних частот для значений карты глубины; всё, что ниже него, обнуляется. Диапазон: [0, 1].

  • Name
    remove_background
    Type
    boolean
    по умолчанию true
    Description

    Автоматически удаляет фон концептуального изображения прототипа перед формированием рельефа.

    Не путать с одноимённым параметром прототипа (значение по умолчанию false), который управляет тем, возвращается ли само изображение прототипа с прозрачностью.

  • Name
    export_resolution
    Type
    integer
    по умолчанию 512
    Description

    Разрешение сетки, используемое для экспорта. Диапазон: [64, 2048].

output

Необязательный селектор формата передачи данных. По умолчанию — glb.

  • Name
    format
    Type
    string
    по умолчанию glb
    Description

    Набор артефактов, возвращаемых сборкой. Доступные значения:

    • glb (по умолчанию) — возвращает единый файл model.glb в model_urls.glb.
    • obj — упаковывает model.obj + model.mtl + texture.png в архив и возвращает его в model_urls.obj.
    • zip — упаковывает все артефакты, создаваемые генератором, в архив и возвращает его в model_urls.bundle_zip.

Возвращаемое значение

Свойство result ответа содержит id задачи новосозданной сборки брелока. Опрашивайте эндпоинт Получение задачи или подпишитесь на поток, пока задача не достигнет статуса SUCCEEDED, а затем загрузите артефакт по единственной записи в model_urls.

Возможные ошибки

  • Name
    400 - Bad Request
    Description

    Запрос был некорректным. Распространённые причины:

    • Отсутствует параметр: обязателен input_task_id.
    • Недопустимый UUID: input_task_id не является допустимым UUID.
    • Родительская задача не завершена успешно: указанная задача прототипа ещё не достигла статуса SUCCEEDED.
    • Нет кандидата: задача прототипа завершилась успешно, но не сгенерировала ни одного изображения-кандидата.
    • Параметры вне диапазона: одно из полей options вышло за пределы допустимого диапазона или набора перечисляемых значений.
  • Name
    401 - Unauthorized
    Description

    Ошибка аутентификации. Проверьте свой API-ключ.

  • Name
    402 - Payment Required
    Description

    Недостаточно кредитов для выполнения этой задачи.

  • Name
    404 - Not Found
    Description

    Указанная задача прототипа не существует, принадлежит другому пользователю или была создана через веб-приложение (в сборку могут быть встроены только задачи прототипов, созданные в режиме API).

  • Name
    429 - Too Many Requests
    Description

    Вы превысили ограничение частоты запросов.

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"
}
Пример сборки
Задача сборки преобразует выбранное изображение прототипа в 3D-печатную модель брелока.
Предпросмотр модели сборки брелока Creative Lab
Предпросмотр модели сборки
GET/openapi/creative-lab/keychain/v1/(prototype|build)/:id

Получение задачи брелока

Получение задачи прототипа или сборки по действительному id задачи. Путь URL должен соответствовать стадии задачи — задача сборки, запрошенная через /prototype/:id, возвращает 404, и наоборот.

Обратитесь к разделам Объект задачи прототипа брелока и Объект задачи сборки брелока для ознакомления с форматами ответов.

Параметры

  • Name
    id
    Type
    path
    Description

    Уникальный идентификатор задачи брелока для получения.

Возвращает

Ответ содержит объект задачи брелока. Формат зависит от того, какая стадия была запрошена.

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

Delete a Keychain Task

Отменяет задачу брелока. Если задача всё ещё находится в состоянии PENDING, кредиты, израсходованные при создании, возвращаются. Задачи, которые уже находятся в состоянии IN_PROGRESS, отменяются без возврата средств (воркер может уже расходовать ресурсы). Задачи, которые уже достигли конечного состояния (SUCCEEDED, FAILED, CANCELED), не могут быть отменены.

Путь URL должен соответствовать этапу задачи — DELETE для /prototype/:buildId возвращает 404.

Параметры пути

  • Name
    id
    Type
    path
    Description

    Уникальный идентификатор задачи брелока для отмены.

Возвращаемое значение

Возвращает 204 No Content при успехе с пустым телом.

Режимы отказа

  • Name
    400 - Bad Request
    Description

    Задача уже находится в конечном состоянии и не может быть отменена.

  • Name
    404 - Not Found
    Description

    Задача не существует, принадлежит другому пользователю, или её этап не соответствует пути URL.

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

Потоковая передача задачи брелока

Передавайте обновления задачи брелока в реальном времени через Server-Sent Events (SSE). Путь URL должен соответствовать этапу задачи — открытие потока по адресу /prototype/:buildId/stream приводит к отправке единственной полезной нагрузки event: error с status_code: 404 и закрытию потока.

Параметры

  • Name
    id
    Type
    path
    Description

    Уникальный идентификатор задачи брелока для потоковой передачи.

Возвращает

Возвращает поток объектов задачи Keychain Prototype или Keychain Build в виде Server-Sent Events. Каждый кадр содержит полный объект задачи для данного этапа — ту же структуру, что возвращает эндпоинт Get, — поэтому пока задача находится в статусе PENDING или IN_PROGRESS, выходные поля просто ещё не заполнены (null, [] или {}), а finished_at равно 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

Получите постраничный список задач вашего брелока для одного этапа. Путь URL выбирает этап — /prototype возвращает задачи прототипирования; /build возвращает задачи сборки. Задачи другого этапа не включаются ни в один из ответов.

Параметры пути

  • Name
    stage
    Type
    path
    Обязательный
    Description

    Либо prototype, либо build. Коллекция возвращает только задачи, этап которых соответствует URL — запрос /prototype никогда не возвращает задачи сборки, и наоборот.

Параметры запроса

  • Name
    page_num
    Type
    integer
    по умолчанию 1
    Description

    Номер страницы для пагинации.

  • Name
    page_size
    Type
    integer
    по умолчанию 10
    Description

    Ограничение размера страницы. Максимально допустимое значение — 100 элементов.

  • Name
    sort_by
    Type
    string
    по умолчанию -created_at
    Description

    Поле для сортировки. Доступные значения:

    • +created_at: Сортировка по времени создания в порядке возрастания.
    • -created_at: Сортировка по времени создания в порядке убывания.

Возвращаемые значения

Возвращает постраничный список объектов задач для данного этапа — либо объект задачи прототипирования брелока при получении списка /prototype, либо объект задачи сборки брелока при получении списка /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=***"
    ]
  }
]

Объект Keychain Prototype Task

Объект Keychain Prototype Task — это единица работы, которую Meshy отслеживает для создания раскрашенного концептуального изображения из исходной фотографии. Результат этого этапа передаётся в этап сборки через input_task_id.

Свойства

  • Name
    id
    Type
    string
    Description

    Уникальный идентификатор задачи. Хотя в качестве деталей реализации мы используем k-sortable UUID для идентификаторов задач, вам не следует делать никаких предположений о формате id.

  • Name
    type
    Type
    string
    Description

    Тип задачи. Значение — creative-lab-keychain-prototype.

  • Name
    name
    Type
    string
    Description

    Имя задачи, указанное при её создании. Пустая строка, если имя не было указано.

  • Name
    name_text
    Type
    string
    Description

    Гравировка, применённая к этому брелоку, после обрезки и удаления невидимых символов форматирования. Отсутствует, если задача была создана без name_text. Сравните это значение с тем, что вы отправили, чтобы убедиться, что текст пережил кодирование вашего HTTP-клиента.

  • Name
    status
    Type
    string
    Description

    Статус задачи. Возможные значения: PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Прогресс выполнения задачи. Если задача ещё не начата, это свойство будет равно 0. После успешного завершения задачи оно станет равным 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Временная метка создания задачи, в миллисекундах.

    Временная метка представляет собой количество миллисекунд, прошедших с 1 января 1970 года UTC, согласно стандарту RFC 3339. Например, пятница, 1 сентября 2023 года, 12:00:00 по Гринвичу представлена как 1693569600000. Это применимо ко всем временным меткам в Meshy API.

  • Name
    started_at
    Type
    timestamp
    Description

    Временная метка начала выполнения задачи, в миллисекундах. Если задача ещё не начата, это свойство будет равно 0.

  • Name
    finished_at
    Type
    timestamp
    Description

    Временная метка завершения задачи, в миллисекундах. Если задача ещё не завершена, это свойство будет равно 0.

  • Name
    expires_at
    Type
    timestamp
    Description

    Временная метка истечения срока действия результата задачи, в миллисекундах.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Количество предшествующих задач.

    Значение этого поля имеет смысл только если статус задачи — PENDING.

  • Name
    task_error
    Type
    object
    Description

    Сведения об ошибке для неудавшихся задач. Полное описание объекта task_error см. в разделе Ошибки.

  • Name
    consumed_credits
    Type
    integer
    Description

    Количество кредитов, потраченных на выполнение этой задачи. Присутствует, когда статус задачи — PENDING, IN_PROGRESS или SUCCEEDED. Возвращает 0 для задач со статусом FAILED (кредиты возвращаются при неудаче).

  • Name
    image_urls
    Type
    array of strings
    Description

    Ссылки для скачивания кандидатов концептуальных изображений, сгенерированных этой задачей прототипа. В настоящее время API всегда возвращает ровно одного кандидата; поле представлено в виде массива, чтобы будущие версии могли предоставлять несколько кандидатов без обратной несовместимости.

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=***"
  ]
}

Объект задачи сборки брелока (Keychain Build Task)

Объект Keychain Build Task — это единица работы, отслеживаемая Meshy для генерации итоговой 3D-сетки брелока на основе успешно завершённой задачи-прототипа. Сборка запускает конвейер рельефа по карте глубины на изображении-концепте прототипа и публикует единый артефакт сетки в формате, запрошенном вызывающей стороной.

Свойства

  • Name
    id
    Type
    string
    Description

    Уникальный идентификатор задачи.

  • Name
    type
    Type
    string
    Description

    Тип задачи. Значение — creative-lab-keychain-build.

  • Name
    name
    Type
    string
    Description

    Имя задачи, указанное при её создании. Пустая строка, если имя не было указано.

  • Name
    status
    Type
    string
    Description

    Статус задачи. Возможные значения: одно из PENDING, IN_PROGRESS, SUCCEEDED, FAILED, CANCELED.

  • Name
    progress
    Type
    integer
    Description

    Progress задачи. Если задача ещё не начата, это свойство будет равно 0. Как только задача успешно завершится, значение станет 100.

  • Name
    created_at
    Type
    timestamp
    Description

    Временная метка создания задачи, в миллисекундах.

  • Name
    started_at
    Type
    timestamp
    Description

    Временная метка начала выполнения задачи, в миллисекундах.

  • Name
    finished_at
    Type
    timestamp
    Description

    Временная метка завершения задачи, в миллисекундах.

  • Name
    expires_at
    Type
    timestamp
    Description

    Временная метка истечения срока действия результата задачи, в миллисекундах.

  • Name
    preceding_tasks
    Type
    integer
    Description

    Количество предшествующих задач. Имеет значение только когда статус — PENDING.

  • Name
    task_error
    Type
    object
    Description

    Детали ошибки для неудавшихся задач. См. Ошибки для полного описания объекта task_error.

  • Name
    consumed_credits
    Type
    integer
    Description

    Количество кредитов, потраченных на эту задачу. Возвращает 0 для задач со статусом FAILED (кредиты возвращаются в случае неудачи).

  • Name
    model_urls
    Type
    object
    Description

    Ссылки для скачивания сгенерированного артефакта, с ключами по имени артефакта. Всегда содержит ровно одну запись — формат, запрошенный через output.format запроса сборки. Ключ соответствует запрошенному формату:

    • Name
      glb
      Type
      string
      Description

      Ссылка для скачивания файла GLB. Присутствует, когда output.format был glb (значение по умолчанию).

    • Name
      obj
      Type
      string
      Description

      Ссылка для скачивания zip-архива, содержащего model.obj, model.mtl и texture.png. Присутствует, когда output.format был obj.

    • Name
      bundle_zip
      Type
      string
      Description

      Ссылка для скачивания zip-архива со всеми артефактами, создаваемыми генератором. Присутствует, когда output.format был zip.

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=***"
  }
}