Text to 3D API

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

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

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

Create a Text to 3D Preview Task

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

Параметры

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

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

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

    Опишите, каким должен быть объект 3D-модели. Максимум 800 символов.

  • 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 — более чистая 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 (others)
    Description

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

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

    Укажите topology генерируемой модели.

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

    • 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-зрение для автоматической оценки реального размера объекта по высоте и соответствующего изменения размера модели. Начало координат по умолчанию будет bottom, если только origin_at не задано явно.

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

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

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

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

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

Режимы сбоя

  • Name
    400 - Bad Request
    Description

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

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

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

  • Name
    402 - Payment Required
    Description

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

  • Name
    429 - Too Many Requests
    Description

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

Request

POST
/openapi/v2/text-to-3d
# Simple preview with required params only
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"
}'

# Preview with remesh and A-pose
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 Refine

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

Параметры

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

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

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

    Идентификатор соответствующей preview-задачи.

    Статус указанной preview-задачи должен быть SUCCEEDED.

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

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

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

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

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

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

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

  • Name
    texture_prompt
    Type
    string
    Description

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

  • Name
    texture_image_url
    Type
    string
    Description

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

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

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

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

  • Name
    ai_model
    Type
    string
    по умолчанию inherited from the preview task
    Description

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

    Опустите этот параметр, чтобы унаследовать модель, использованную в preview-задаче — это сохраняет preview и её refine на одной и той же модели от начала до конца. Передайте явное значение, чтобы переопределить это наследование.

    Явное значение latest разрешается здесь точно так же, как и в preview-задаче (в настоящее время Meshy 7), поэтому preview с latest и её refine с 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, задача дополнительно рендерит версию preview с прозрачным фоном (RGBA) и возвращает её как alpha_thumbnail_url в ответе на GET-запрос. Существующее поле thumbnail_url остаётся без изменений.

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

    Если установлено значение true, сервис использует AI-зрение для автоматической оценки реального размера объекта по высоте и соответствующего изменения размера модели. Начало координат по умолчанию будет 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

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

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

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

  • Name
    402 - Payment Required
    Description

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

  • Name
    404 - Not Found
    Description

    Preview-задача, указанная в preview_task_id, не найдена.

  • Name
    429 - Too Many Requests
    Description

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

Request

POST
/openapi/v2/text-to-3d
# Basic refine task
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
}'

# Refine with auto-size and GLB format
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

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

Этот эндпоинт работает как для задач preview, так и для задач refine.

Параметры

  • Name
    id
    Type
    path
    Description

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

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

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

Примеры

РежимПример модели
PreviewPreview model
RefineRefined 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

Удалить задачу Текст в 3D

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

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

  • Name
    id
    Type
    path
    Description

    ID задачи Текст в 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

// Returns 200 Ok on success.
GET/openapi/v2/text-to-3d

List Text to 3D Tasks

Этот эндпоинт позволяет получить список задач Текст в 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: Сортировка по времени создания в порядке убывания.

Возвращает

Возвращает список объектов задачи Текст в 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

Потоковая передача задачи Текст в 3D

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

Параметры

  • Name
    id
    Type
    path
    Description

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

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

Возвращает поток объектов задачи Текст в 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

// Error event example
event: error
data: {
  "status_code": 404,
  "message": "Task not found"
}

// Message event examples illustrate task progress.
// For PENDING or IN_PROGRESS tasks, the response stream will not include all fields.
event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 0,
  "status": "PENDING"
}

event: message
data: {
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "progress": 50,
  "status": "IN_PROGRESS"
}

event: message
data: {
"id": "018a210d-8ba4-705c-b111-1f1776f7f578",
"type": "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-модели на основе текстового ввода. Text to 3D API имеет два этапа: preview и refine. Этап preview предназначен для генерации 3D-модели только с сеткой, а этап refine — для генерации текстурированной 3D-модели на основе результата этапа preview.

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

Свойства

  • Name
    id
    Type
    string
    Description

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

  • Name
    type
    Type
    string
    Description

    Тип задачи Text to 3D. Возможные значения: text-to-3d-preview для задач этапа preview и text-to-3d-refine для задач этапа 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, использованный для создания задачи preview. Не поддерживается Meshy-6.

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

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

  • Name
    texture_prompt
    Type
    string
    Description

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

  • Name
    ultra_mode
    Type
    boolean
    Description

    Отражает значение ultra_mode, с которым была создана задача preview. Присутствует только для задач preview 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 PM 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
}