lowpoly будет отключён 30 окт. 2026 г.. Перейдите на другую модель до этих дат, чтобы избежать ошибок в запросах.

API Текст в 3D

API Текст в 3D — это функция, которая позволяет интегрировать возможности 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 или meshy-t2.5).
    • lowpoly (устаревшее, будет снято с поддержки 30 октября 2026 года): Генерирует низкополигональную сетку, оптимизированную для более чистых полигонов. Рекомендуем вместо этого Meshy T2.5: smart-topology с meshy-t2.5.

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

    lowpoly будет снято с поддержки 30 октября 2026 года. После этой даты запросы с model_type: "lowpoly" будут возвращать ошибку. Рекомендуем перейти на Meshy T2.5 (model_type: "smart-topology" с ai_model: "meshy-t2.5"). При выборе lowpoly параметры ai_model, topology, target_polycount и should_remesh игнорируются.

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

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

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

    • meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
    • meshy-7 (устаревшее): используйте вместо этого meshy-7.1.

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

    • meshy-t2: модель Smart Topology — более чистая topology, нативно разделённые части, вывод в виде треугольников и число граней, которое можно задать с помощью target_polycount.
    • meshy-t2.5 (по умолчанию): Более чёткая детализация для игровых ассетов. Вывод в виде треугольников и число граней, которое можно задать с помощью target_polycount.
  • Name
    geometry_resolution
    Type
    string
    по умолчанию standard
    Description

    Этап генерации геометрии. 2k запускает проход Ultra с разрешением 2048³; 4k запускает его с разрешением 4096³ для наиболее тонкой детализации поверхности.

    Доступные значения: standard, 2k, 4k

    Поддерживается только в режиме preview. Требует meshy-7.1 или latest.

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

    Используйте вместо этого geometry_resolution. ultra_mode: true эквивалентно geometry_resolution: "2k".

  • Name
    should_remesh
    Type
    boolean
    по умолчанию false (Meshy 6 and Meshy 7 models), 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 или meshy-t2.5 возвращает ошибку.

  • 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 или meshy-t2.5. Модель генерируется напрямую с этим числом граней; ремешинг не выполняется, и should_remesh не требуется. Для meshy-t2: диапазон от 100 до 15 000, значение по умолчанию 4 000. Для meshy-t2.5: диапазон от 100 до 30 000, значение по умолчанию 15 000.
  • Name
    symmetry_mode
    Type
    string
    ⚠ устаревший
    по умолчанию auto
    Description

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

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

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

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

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

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

    • 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 превышает лимит символов.
    • Неподдерживаемая модель для низкополигональной сетки: ai_model: "meshy-6-lite" не поддерживает model_type: "lowpoly".
    • Неподдерживаемая модель для Ultra: geometry_resolution требует meshy-7.1 или latest.
  • 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 Ultra 4K geometry, 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",
  "ai_model": "meshy-7.1",
  "geometry_resolution": "4k",
  "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

Создание задачи Refine для Text to 3D

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

Задача выполняется в фоновом режиме. О том, сколько времени это обычно занимает, см. в разделе Время обработки.

Параметры

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

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

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

    Соответствующий id задачи preview.

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

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

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

  • 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.1 или 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 и .webp.

    Максимальный размер файла: 20 МБ.

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

    • Общедоступный 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
    по умолчанию inherited from the preview task
    Description

    ID модели, используемой для refine.

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

    • meshy-6-lite, meshy-6, meshy-7.1, latest (Meshy 7.1)
    • meshy-7 (устаревшее): используйте вместо этого meshy-7.1.

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

    Явное значение latest разрешается здесь точно так же, как и в задаче preview (в настоящее время это Meshy 7.1), поэтому 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.1 и latest принимают этот параметр, но игнорируют его, так же как и refine preview-модели meshy-t2, для которой не задан ai_model. Установка этого параметра с meshy-6-lite приводит к ошибке.

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

    Запрос недопустим. Распространённые причины:

    • Недействительный ID задачи: preview_task_id недействителен или не существует.
    • Задача не готова: задача preview ещё не завершилась успешно.
    • Несоответствие моделей: AI-модель задачи preview несовместима с запрошенной моделью refine.
    • Неподдерживаемая модель для remove_lighting: remove_lighting задан вместе с ai_model: "meshy-6-lite".
  • 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.

Примеры

ModeПример модели
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, которую нужно удалить.

Статус задачи

Задача, которая всё ещё находится в статусе PENDING, удаляется, а кредиты, списанные при её создании, возвращаются.

Задачу, которая уже находится в статусе IN_PROGRESS, удалить нельзя: запрос отклоняется с ошибкой 409 Conflict, а задача продолжает выполняться. Кредиты за задачу, выполнение которой уже начал воркер, не подлежат возврату, поэтому удаление её в процессе выполнения привело бы к потере и кредитов, и результата. Дождитесь, пока она перейдёт в статус SUCCEEDED, FAILED или CANCELED, и только потом удаляйте её.

Задача в конечном статусе (SUCCEEDED, FAILED или CANCELED) удаляется без возврата средств.

Возвращает

Возвращает 200 OK при успехе или 409 Conflict, если задача находится в статусе IN_PROGRESS.

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 on success, with an empty body.
//
// 409 Conflict when the task is IN_PROGRESS — the task is left running:
{
  "message": "Task is IN_PROGRESS and cannot be deleted. Credits for a task the worker has already started are not refundable; wait for it to reach SUCCEEDED, FAILED or CANCELED, then delete it."
}
GET/openapi/v2/text-to-3d

Список задач Текст в 3D

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

Параметры

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

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

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

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

  • 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

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

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

Параметры

  • Name
    id
    Type
    path
    Description

    Уникальный идентификатор задачи Текст в 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

// 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-sortable 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

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

    • Name
      glb
      Type
      string
      Description

      Скачиваемая ссылка на файл GLB.

    • Name
      fbx
      Type
      string
      Description

      Скачиваемая ссылка на файл FBX.

    • Name
      usdz
      Type
      string
      Description

      Скачиваемая ссылка на файл USDZ.

    • Name
      obj
      Type
      string
      Description

      Скачиваемая ссылка на файл OBJ.

    • Name
      mtl
      Type
      string
      Description

      Скачиваемая ссылка на файл MTL.

    • Name
      stl
      Type
      string
      Description

      Скачиваемая ссылка на файл STL.

    • Name
      3mf
      Type
      string
      Description

      Скачиваемая ссылка на файл 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

    Устаревшее; используйте вместо этого geometry_resolution.

  • Name
    geometry_resolution
    Type
    string
    Description

    Уровень Ultra, с которым выполнялась задача preview (2k или 4k); отсутствует для standard.

  • Name
    texture_image_url
    Type
    string
    Description

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

  • Name
    thumbnail_url
    Type
    string
    Description

    Скачиваемая ссылка на миниатюру файла модели.

  • Name
    alpha_thumbnail_url
    Type
    string
    Description

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

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

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

  • 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 по Гринвичу представляется как 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

      Скачиваемая ссылка на изображение карты базового цвета.

    • Name
      metallic
      Type
      string
      Description

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

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

    • Name
      normal
      Type
      string
      Description

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

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

    • Name
      roughness
      Type
      string
      Description

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

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

    • Name
      emission
      Type
      string
      Description

      Скачиваемая ссылка на изображение карты излучения.

      Если задача создана с enable_pbr: false, если ai_model имеет значение meshy-6-lite, meshy-7.1 или latest, или если задача выполняет refine превью meshy-t2 без установки ai_model, это свойство будет отсутствовать.

  • 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
}