Text to 3D API

Text to 3D API — это функция, которая позволяет интегрировать возможности "Текста в 3D" от Meshy в ваше собственное приложение. В этом разделе вы найдете всю необходимую информацию для начала работы с этим API.

Text to 3D использует двухэтапный рабочий процесс. Сначала создайте задачу предпросмотра (mode: "preview"), чтобы сгенерировать 3D сетку без текстуры и оценить форму. Затем передайте идентификатор задачи завершенного предпросмотра в задачу уточнения (mode: "refine"), чтобы применить текстуру к сетке. Оба шага используют один и тот же эндпоинт.

POST/openapi/v2/text-to-3d

Создание задачи Text to 3D предпросмотра

Этот эндпоинт создает задачу предпросмотра Text to 3D, которая генерирует 3D сетку без текстуры (только геометрия) из текстового prompt. Это первый шаг двухэтапного рабочего процесса. Как только предпросмотр будет успешным, используйте возвращенный идентификатор задачи для создания уточняющей задачи для текстурирования. Обратитесь к Объект задачи Text to 3D для полной схемы ответа.

Параметры

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

    Это поле должно быть установлено на "preview" при создании задачи предпросмотра.

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

    Опишите, что представляет собой 3D модель. Максимум 600 символов.

  • Name
    model_type
    Type
    string
    по умолчанию standard
    Description

    Укажите тип генерации 3D сетки.

    Доступные значения:

    • standard: Обычная генерация детализированной 3D сетки.
    • smart-topology: Выберите модель Smart Topology с ai_model (meshy-t2).
    • lowpoly (устаревшее): Генерирует низкополигональную сетку, оптимизированную для чистых полигонов. Мы рекомендуем использовать smart-topology вместо этого.

    При выборе smart-topology, should_remesh и decimation_mode игнорируются, и принимается только topology: triangle.

    Когда выбрано lowpoly, ai_model, topology, target_polycount и should_remesh игнорируются.

  • Name
    ai_model
    Type
    string
    по умолчанию latest
    Description

    ID модели для использования. Доступные значения зависят от model_type.

    Стандартная генерация (model_type: standard):

    • meshy-5, meshy-6, meshy-7, latest (Meshy 7)

    Генерация Smart Topology (model_type: smart-topology):

    • meshy-t2 (по умолчанию): модель Smart Topology — более чистая топология, нативно разделенные части, треугольный выход и количество граней, которое можно задать с помощью target_polycount.
  • Name
    ultra_mode
    Type
    boolean
    по умолчанию false
    Description

    Включает Ultra генерацию для более точной геометрии с более тонкими поверхностными деталями. Генерация занимает больше времени и добавляет 5 кредитов.

    Поддерживается только при использовании ai_model meshy-7 (или latest) и только в режиме preview.

  • Name
    should_remesh
    Type
    boolean
    по умолчанию false (meshy-6, meshy-7), true (другие)
    Description

    Управляет активацией фазы ремешинга. Для модели наивысшего качества мы рекомендуем устанавливать should_remesh в false.

Применяется только когда should_remesh = true
  • Name
    topology
    Type
    string
    по умолчанию triangle
    Description

    Укажите топологию создаваемой модели.

    Доступные значения:

    • quad: Сгенерировать сетку с преобладанием квадов.
    • triangle: Сгенерировать упрощенную треугольную сетку.

    Вывод Smart Topology только треугольный. Запрос quad вместе с ai_model: meshy-t2 возвращает ошибку.

  • Name
    decimation_mode
    Type
    integer
    Description

    Включите адаптивное уменьшение, установив уровень числа полигонов. При установке target_polycount игнорируется.

    Доступные значения:

    • 1: Адаптивный — ультра количество полигонов.
    • 2: Адаптивный — высокое количество полигонов.
    • 3: Адаптивный — среднее количество полигонов.
    • 4: Адаптивный — низкое количество полигонов.
  • Name
    target_polycount
    Type
    integer
    Description

    Целевое количество полигонов (граней) в выводе. Фактическое количество может отклоняться от заданного в зависимости от геометрии.

    target_polycount применяется в двух независимых случаях:

    • Ремешинг — с should_remesh: true для модели standard. Сетка ремешируется (уменьшается) приблизительно до этого количества. Диапазон от 100 до 300 000, по умолчанию 30 000. Если decimation_mode установлен, он имеет приоритет, и target_polycount игнорируется.
    • Smart Topology — с model_type: smart-topology и ai_model: meshy-t2. Модель генерируется непосредственно с этим количеством граней; ремешинг не выполняется и should_remesh не требуется. Диапазон от 100 до 15 000, по умолчанию 4 000.
  • Name
    symmetry_mode
    Type
    string
    ⚠ устаревший
    по умолчанию auto
    Description

    Устарело. Этот параметр больше не влияет на вывод.

    Поле symmetry_mode управляет симметрией во время процесса генерации модели.

    Допустимые значения:

    • off: Отключить симметрию.
    • auto: Автоматически определяет и применяет симметрию на основе входной геометрии.
    • on: Принудительное применение симметрии во время генерации.
  • Name
    pose_mode
    Type
    string
    по умолчанию ""
    Description

    Укажите режим позы для создаваемой модели.

    Доступные значения:

    • a-pose: Создать модель в позе A.
    • t-pose: Создать модель в позе T.
    • "" (пустая строка): Не применять конкретную позу.
  • Name
    is_a_t_pose
    Type
    boolean
    ⚠ устаревший
    по умолчанию false
    Description

    Используйте pose_mode вместо этого. Устанавливает, будет ли модель сгенерирована в позе A/T.

  • Name
    art_style
    Type
    string
    ⚠ устаревший
    по умолчанию realistic
    Description

    Не поддерживается Meshy-6. Запросы с использованием Meshy-6 будут игнорировать art_style, и некоторые комбинации могут вызывать ошибки. Доступные значения: realistic, sculpture.

    enable_pbr должен быть установлен на false при использовании стиля Sculpture, так как стиль Sculpture генерирует собственный набор PBR-карт.

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

    При установке на true, входной контент будет автоматически проверяться на потенциально вредное содержание. Если вредное содержание будет обнаружено, задача не будет продолжена для генерации.

    Текст из prompt будет проверен.

  • Name
    target_formats
    Type
    string[]
    Description

    Указывает, какие форматы 3D файлов включить в вывод. Только запрошенные форматы будут сгенерированы и возвращены, что может сократить время завершения задачи. Если не указано, включены все поддерживаемые форматы.

    Доступные значения: glb, obj, fbx, stl, usdz, 3mf

    Если не указано, все форматы, кроме 3mf, генерируются. 3mf включается только при явном указании.

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

    При установке на true, задача дополнительно рендерит версию предпросмотра с прозрачным фоном (RGBA) и возвращает ее как alpha_thumbnail_url в ответе GET. Существующее поле thumbnail_url не изменяется.

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

    При установке на true, служба использует AI vision для автоматической оценки реальной высоты объекта и изменения размера модели соответственно. По умолчанию начало координат будет установлено на bottom, если origin_at не указан явно.

Применяется только когда auto_size = true
  • Name
    origin_at
    Type
    string
    по умолчанию bottom
    Description

    Положение начала координат, когда auto_size включен.

    Доступные значения: bottom, center.

Возврат

Свойство result ответа содержит id задачи вновь созданной задачи Text to 3D.

Режимы сбоя

  • Name
    400 - Bad Request
    Description

    Запрос был неприемлемым. Общие причины:

    • Отсутствующий параметр: Отсутствует обязательный параметр (например, prompt, mode).
    • Недопустимый параметр: art_style не является одним из допустимых значений.
    • Prompt слишком долгий: prompt превышает ограничение на количество символов.
  • Name
    401 - Unauthorized
    Description

    Аутентификация не удалась. Пожалуйста, проверьте ваш API key.

  • Name
    402 - Payment Required
    Description

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

  • Name
    429 - Too Many Requests
    Description

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

Request

POST
/openapi/v2/text-to-3d
# Простой предпросмотр только с обязательными параметрами
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a monster mask"
}'

# Предпросмотр с ремешингом и позой A
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "preview",
  "prompt": "a futuristic robot warrior",
  "should_remesh": true,
  "target_polycount": 100000,
  "pose_mode": "a-pose",
  "target_formats": ["glb"]
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
POST/openapi/v2/text-to-3d

Создание задачи Text to 3D уточнения

Этот эндпоинт создает задачу Text to 3D уточнения, которая применяет текстуру к завершенной сетке предпросмотра. Вы должны предоставить preview_task_id из успешной задачи предпросмотра. Это второй шаг двухэтапного рабочего процесса.

Параметры

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

    Это поле должно быть установлено на "refine" при создании задачи уточнения.

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

    Соответствующий идентификатор задачи предпросмотра.

    Статус заданной задачи предпросмотра должен быть SUCCEEDED.

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

    Генерировать PBR карты (metallic, roughness, normal) в дополнение к базовому цвету. Также включена карта emissive, когда ai_model — meshy-6, за исключением texture_resolution: 8k (никакая карта emissive не создается). meshy-7 (и latest) не создают карту emissive.

  • Name
    texture_resolution
    Type
    string
    по умолчанию 2k
    Description

    Разрешение текстуры базового цвета. Одно из 2k (2048×2048), 4k (4096×4096) или 8k (8192×8192). Более высокие разрешения позволяют захватить больше деталей поверхности. Применяется только к режиму refine.

    4k и 8k требуют ai_model meshy-6, meshy-7 или latest. При 8k карта emissive не создается.

  • Name
    hd_texture
    Type
    boolean
    ⚠ устаревший
    по умолчанию false
    Description

    Используйте texture_resolution вместо этого — эквивалентно texture_resolution: "4k". Когда оба параметра установлены, texture_resolution имеет приоритет.

  • Name
    texture_prompt
    Type
    string
    Description

    Предоставьте дополнительный текстовый prompt для направляющей процесса текстурирования. Максимум 600 символов.

  • Name
    texture_image_url
    Type
    string
    Description

    Предоставьте 2D изображение для направляющей процесса текстурирования. В настоящее время поддерживаются форматы .jpg, .jpeg и .png.

    Есть два способа предоставить изображение:

    • Доступный общедоступный URL: URL, доступный из общественного интернета
    • Data URI: закодированный в base64 Data URI изображения. Пример Data URI: data:image/jpeg;base64,<your base64-encoded image data>

    Текстурирование изображениями может работать не оптимально, если существуют значительные различия в геометрии между исходным asset и загруженным изображением. Может использоваться только один из texture_image_url или texture_prompt, чтобы направить процесс текстурирования. Если оба параметра указаны, по умолчанию будет использоваться texture_prompt.

  • Name
    ai_model
    Type
    string
    по умолчанию latest
    Description

    ID модели для использования при уточнении. Доступные значения: meshy-5, meshy-6, meshy-7, latest (Meshy 7).

    latest разрешается также, как в задаче предпросмотра (в настоящее время Meshy 7), так что предпросмотр latest и его уточнение latest всегда заканчиваются на одной модели текстуры.

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

    При установке на true, входной контент будет автоматически проверяться на потенциально вредное содержание. Если вредное содержание будет обнаружено, задача не будет продолжена для генерации.

    Будут проверены как текст из texture_prompt, так и изображение из texture_image_url.

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

    Удаляет блики и тени с базовой текстуры цвета, создавая более чистый результат, который лучше работает в условиях пользовательского освещения.

    Применяется только, когда ai_model — meshy-6. На meshy-7 (и latest) параметр принимается, но игнорируется.

  • Name
    target_formats
    Type
    string[]
    Description

    Указывает, какие форматы 3D файлов включить в вывод. Только запрошенные форматы будут сгенерированы и возвращены, что может сократить время завершения задачи. Если не указано, включены все поддерживаемые форматы.

    Доступные значения: glb, obj, fbx, stl, usdz, 3mf

    Если не указано, все форматы, кроме 3mf, генерируются. 3mf включается только при явном указании.

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

    При установке на true, задача дополнительно рендерит версию предпросмотра с прозрачным фоном (RGBA) и возвращает ее как alpha_thumbnail_url в ответе GET. Существующее поле thumbnail_url не изменяется.

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

    При установке на true, служба использует AI vision для автоматической оценки реальной высоты объекта и изменения размера модели соответственно. По умолчанию начало координат будет установлено на bottom, если origin_at не указан явно.

Применяется только когда auto_size = true
  • Name
    origin_at
    Type
    string
    по умолчанию bottom
    Description

    Положение начала координат, когда auto_size включен.

    Доступные значения: bottom, center.

Возврат

Свойство result ответа содержит id задачи вновь созданной задачи Text to 3D.

Режимы сбоя

  • Name
    400 - Bad Request
    Description

    Запрос был неприемлемым. Общие причины:

    • Недопустимый идентификатор задачи: preview_task_id является недопустимым или не существует.
    • Задача не готова: задача предпросмотра еще не завершилась успехом.
    • Несоответствие модели: модель AI задачи предпросмотра несовместима с запрашиваемой моделью уточнения.
  • Name
    401 - Unauthorized
    Description

    Аутентификация не удалась. Пожалуйста, проверьте ваш API key.

  • Name
    402 - Payment Required
    Description

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

  • Name
    404 - Not Found
    Description

    Задача предпросмотра, указанная preview_task_id, не найдена.

  • Name
    429 - Too Many Requests
    Description

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

Request

POST
/openapi/v2/text-to-3d
# Базовая уточняющая задача
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "enable_pbr": true
}'

# Уточнение с автоматическим размером и форматом GLB
curl https://api.meshy.ai/openapi/v2/text-to-3d \
  -H 'Authorization: Bearer ${YOUR_API_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "refine",
  "preview_task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "target_formats": ["glb"],
  "auto_size": true
}'

Response

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}
GET/openapi/v2/text-to-3d/:id

Получить задачу Text to 3D

Этот эндпоинт позволяет вам получить задачу Text to 3D, указав действительный id задачи. Обратитесь к разделу Объект задачи Text to 3D, чтобы увидеть, какие свойства включены в объект задачи Text to 3D.

Этот эндпоинт работает как для задач предпросмотра, так и для уточняющих задач.

Параметры

  • Name
    id
    Type
    path
    Description

    Уникальный идентификатор для задачи Text to 3D, которую нужно получить.

Возврат

Ответ содержит объект задачи Text to 3D. Подробности смотрите в разделе Объект задачи Text to 3D.

Примеры

РежимОбразец модели
ПредпросмотрPreview model
УточнениеRefined model

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?Expires=***",
    "usdz": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.usdz?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=***",
  "prompt": "a monster mask",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "finished_at": 1692771669037,
  "status": "SUCCEEDED",
  "texture_urls": [
    {
      "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
    }
  ],
  "preceding_tasks": 0,
  "task_error": {

    "message": ""

  },

  "consumed_credits": 20
}
DELETE/openapi/v2/text-to-3d/:id

Удалить задачу Text to 3D

Этот эндпоинт навсегда удаляет задачу Text to 3D, включая все связанные модели и данные. Это действие не может быть отменено.

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

  • Name
    id
    Type
    path
    Description

    Идентификатор задачи Text to 3D для удаления.

Возврат

Возвращает 200 OK при успешном выполнении.

Request

DELETE
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578
curl --request DELETE \
  --url https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578 \
  -H "Authorization: Bearer ${YOUR_API_KEY}"

Response

// Возвращает 200 Ok при успешном выполнении.
GET/openapi/v2/text-to-3d

Список задач Text to 3D

Этот эндпоинт позволяет вам получить список задач Text to 3D.

Параметры

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

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

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

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

  • Name
    sort_by
    Type
    string
    Description

    Поле для сортировки.

    Доступные значения:

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

Возврат

Возвращает пагинированный список Объектов задачи Text to 3D.

Request

GET
/openapi/v2/text-to-3d
curl https://api.meshy.ai/openapi/v2/text-to-3d?page_size=10 \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "type": "text-to-3d-preview",
    "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=***",
      "mtl": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.mtl?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=***",
    "prompt": "a monster mask",
    "progress": 100,
    "started_at": 1692771667037,
    "created_at": 1692771650657,
    "finished_at": 1692771669037,
    "status": "SUCCEEDED",
    "texture_urls": [
      {
        "base_color": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/texture_0.png?Expires=***"
      }
    ],
    "preceding_tasks": 0,
    "task_error": {

      "message": ""

    },

    "consumed_credits": 20
  }
]
GET/openapi/v2/text-to-3d/:id/stream

Трансляция задачи Text to 3D

Этот эндпоинт транслирует обновления в реальном времени для задачи Text to 3D, используя Server-Sent Events (SSE).

Параметры

  • Name
    id
    Type
    path
    Description

    Уникальный идентификатор для задачи Text to 3D, которую нужно транслировать.

Возврат

Возвращает поток Объектов задачи Text to 3D в виде Server-Sent Events.

Для задач PENDING или IN_PROGRESS, поток ответов будет включать только необходимые поля progress и status.

Request

GET
/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream
curl -N https://api.meshy.ai/openapi/v2/text-to-3d/018a210d-8ba4-705c-b111-1f1776f7f578/stream \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response Stream

// Пример события ошибки
event: error
data: {
  "status_code": 404,
  "message": "Задача не найдена"
}

// Примеры событий сообщений иллюстрируют прогресс выполнения задачи.
// Для задач PENDING или IN_PROGRESS поток ответов не будет включать все поля.
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": "text-to-3d-preview",
"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=***"
},
"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": 20
}

Объект задачи Text to 3D

Объект задачи Text to 3D — это рабочая единица, которую Meshy отслеживает для генерации 3D модели из ввода в виде текста. В API Text to 3D есть две стадии, preview и refine. Стадия предпросмотра предназначена для генерации только сеточной 3D модели, а стадия уточнения — для генерации текстурированной 3D модели на основе результата стадии предпросмотра.

Объект имеет следующие свойства:

Свойства

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Тип задачи Text to 3D. Возможные значения — text-to-3d-preview для задач стадии предпросмотра и text-to-3d-refine для задач стадии уточнения.

  • Name
    model_urls
    Type
    object
    Description

    Скачиваемый URL текстурированной 3D модели, созданной Meshy. Свойство для формата будет опущено, если формат не сгенерирован, вместо возврата пустой строки.

    • Name
      glb
      Type
      string
      Description

      Скачиваемый URL файла GLB.

    • Name
      fbx
      Type
      string
      Description

      Скачиваемый URL файла FBX.

    • Name
      usdz
      Type
      string
      Description

      Скачиваемый URL файла USDZ.

    • Name
      obj
      Type
      string
      Description

      Скачиваемый URL файла OBJ.

    • Name
      mtl
      Type
      string
      Description

      Скачиваемый URL файла MTL.

    • Name
      stl
      Type
      string
      Description

      Скачиваемый URL файла STL.

    • Name
      3mf
      Type
      string
      Description

      Скачиваемый URL файла 3MF. Присутствует только, если 3mf был запрошен через target_formats.

  • Name
    prompt
    Type
    string
    Description

    Это неизмененное prompt, который использовался для создания задачи.

  • Name
    negative_prompt
    Type
    string
    ⚠ устаревший
    Description

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

  • Name
    art_style
    Type
    string
    ⚠ устаревший
    Description

    Неизмененный art_style, который использовался для создания задачи предпросмотра. Не поддерживается Meshy-6.

  • Name
    texture_richness
    Type
    string
    ⚠ устаревший
    Description

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

  • Name
    texture_prompt
    Type
    string
    Description

    Дополнительный текстовый запрос, предоставленный для руководства процессом текстурирования во время стадии уточнения.

  • Name
    ultra_mode
    Type
    boolean
    Description

    Возвращает значение ultra_mode, с которым была создана задача предпросмотра. Присутствует только для задач предпросмотра meshy-7 (или latest), в которых явно установлен ultra_mode; в противном случае опущено.

  • Name
    texture_image_url
    Type
    string
    Description

    URL для скачивания текстуры изображения, использованной для управления процессом текстурирования.

  • Name
    thumbnail_url
    Type
    string
    Description

    URL для скачивания миниатюрного изображения файла модели.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

    URL для скачивания версии thumbnail_url с прозрачным фоном (RGBA). Присутствует только, если задача была создана с alpha_thumbnail: true и прозрачный предпросмотр был успешно сгенерирован; иначе это поле отсутствует.

  • Name
    video_url
    Type
    string
    ⚠ устаревший
    Description

    URL для скачивания видео предпросмотра. Будет удалено в будущем выпуске.

  • Name
    progress
    Type
    integer
    Description

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

  • Name
    started_at
    Type
    timestamp
    Description

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

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

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    status
    Type
    string
    Description

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

  • Name
    texture_urls
    Type
    array
    Description

    Массив объектов URL текстур, сгенерированных из задачи. Обычно содержит только один объект URL текстуры. Каждый объект URL текстуры имеет следующие свойства:

    • Name
      base_color
      Type
      string
      Description

      URL для скачивания изображения базовой карты цвета.

    • Name
      metallic
      Type
      string
      Description

      URL для скачивания изображения металлической карты.

      Если задача создана с enable_pbr: false, это свойство будет опущено.

    • Name
      normal
      Type
      string
      Description

      URL для скачивания изображения карты нормалей.

      Если задача создана с enable_pbr: false, это свойство будет опущено.

    • Name
      roughness
      Type
      string
      Description

      URL для скачивания изображения карты шероховатости.

      Если задача создана с enable_pbr: false, это свойство будет опущено.

    • Name
      emission
      Type
      string
      Description

      URL для скачивания изображения карты эмиссии.

      Если задача создана с enable_pbr: false или ai_model — meshy-5, это свойство будет опущено.

  • 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 (кредиты возвращаются в случае неудачи).

Example Text to 3D Task Object

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "type": "text-to-3d-preview",
  "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=***",
    "obj": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/model.obj?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=***"
  },
  "prompt": "a monster mask",
  "texture_prompt": "green slimy skin with scales and warts",
  "texture_image_url": "",
  "thumbnail_url": "https://assets.meshy.ai/***/tasks/018a210d-8ba4-705c-b111-1f1776f7f578/output/preview.png?Expires=***",
  "progress": 100,
  "started_at": 1692771667037,
  "created_at": 1692771650657,
  "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": 20
}