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: Data URI изображения в кодировке base64. Пример Data URI: data:image/jpeg;base64,<your base64-encoded image data>.
  • Name
    name
    Type
    string
    Description

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

Возвращает

Свойство 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 имеет неверный формат.
    • Контент помечен: Входное изображение было помечено NSFW или moderation интеллектуальной собственности.
  • 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' \
  -d '{
    "image_url": "<your publicly accessible image url or base64-encoded data URI>"
  }'

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

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

  • 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 в zip и возвращает набор в model_urls.obj.
    • zip — упаковывает в 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 вышло за пределы разрешенного диапазона или набора enum.
  • Name
    401 - Unauthorized
    Description

    Аутентификация не удалась. Проверьте ваш API-ключ.

  • Name
    402 - Payment Required
    Description

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

  • Name
    404 - Not Found
    Description

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

  • 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"
}
Build example
The build task converts the selected prototype image into a 3D-printable keychain model.
Creative Lab Keychain build model preview
Build model preview

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

Удалить задачу брелока

Отменяет задачу брелока. Если задача всё ещё находится в состоянии 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

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

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

Возвращает поток объектов задач прототипа брелока или сборки брелока в виде Server-Sent Events. Для задач PENDING или IN_PROGRESS поток ответа будет включать только необходимые поля progress и status.

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.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
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)

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

Получите пагинированный список ваших задач брелока для одного этапа. Путь 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

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

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

Объект задачи прототипа брелока

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

Свойства

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

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

  • 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

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    expires_at
    Type
    timestamp
    Description

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

  • Name
    preceding_tasks
    Type
    integer
    Description

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

  • 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

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

Example Keychain Prototype Task Object

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

Объект задачи сборки брелока

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

Свойства

  • 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

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

    • Name
      glb
      Type
      string
      Description

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

    • Name
      obj
      Type
      string
      Description

      Загружаемый URL к zip-пакету, содержащему model.obj, model.mtl и texture.png. Присутствует, когда output.format был obj.

    • Name
      bundle_zip
      Type
      string
      Description

      Загружаемый URL к 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=***"
  }
}