lowpoly будет отключён 30 окт. 2026 г.. meshy-7 как модель 3D-генерации будет отключена 31 дек. 2026 г.; как модель текстурирования она остаётся доступной. Перейдите на другую модель до этих дат, чтобы избежать ошибок в запросах. Все устаревшие функции

Usage API

Получайте список завершённых API-задач вашей команды и количество кредитов, потраченных на каждую из них, для экспорта данных для выставления счетов и отчётов о затратах.

Для вызова этого эндпоинта используйте API-ключ активного участника команды Studio или Enterprise. Вызвать его может любой участник, а не только владельцы и администраторы. При использовании любого другого API-ключа запрос возвращает 403.


GET/openapi/v1/usage/tasks

Список записей использования

Возвращает одну страницу записей использования вашей команды, по умолчанию сначала самые новые. Без start_time и end_time записи охватывают последние 30 дней. Вызов этого эндпоинта бесплатен.

Записи включают следующие задачи:

  • API-задачи, завершившиеся со статусом SUCCEEDED или FAILED
  • Задачи всех текущих участников команды, с любых их API-ключей
  • Удалённые вами задачи и задачи, у которых истёк срок хранения файлов

Записи не включают следующие задачи:

  • Задачи со статусом PENDING или IN_PROGRESS, а также задачи со статусом CANCELED
  • Задачи людей, покинувших команду
  • Задачи Creative Lab
  • Задачи, выполненные ИИ-агентами Meshy
  • Работу, выполненную в веб-приложении Meshy

Задача появляется в записях только после завершения, в окне, соответствующем её created_at. Meshy списывает кредиты в момент создания задачи, поэтому ещё выполняющаяся задача отсутствует в записях. Прежде чем сверять записи с балансом кредитов, повторно запросите недавние окна или выполните экспорт с небольшой задержкой.

Если для вашей команды установлен период хранения данных, окно не может начинаться раньше, чем это допускает данный период.

Request

GET
/openapi/v1/usage/tasks
curl "https://api.meshy.ai/openapi/v1/usage/tasks?page_size=50&start_time=2026-08-01T00:00:00Z&end_time=2026-09-01T00:00:00Z" \
-H "Authorization: Bearer ${YOUR_API_KEY}"

Response

[
  {
    "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
    "endpoint": "image-to-3d",
    "status": "SUCCEEDED",
    "created_at": 1755787000000,
    "finished_at": 1755787045000,
    "consumed_credits": 20,
    "api_key_name": "production",
    "api_key_suffix": "a1b2",
    "metadata": {
      "user": "alex@example.com",
      "team": "fab"
    }
  },
  {
    "task_id": "018a210d-1c22-7e0f-9d3a-4a5b6c7d8e9f",
    "endpoint": "text-to-3d-refine",
    "status": "FAILED",
    "created_at": 1755786000000,
    "finished_at": 1755786030000,
    "consumed_credits": 0,
    "api_key_name": "production",
    "api_key_suffix": "a1b2",
    "metadata": {}
  }
]

Параметры

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

    Возвращаемая страница, от 1 до 255. Значение выше 255 возвращает 400. Одно окно вмещает не более 255 страниц, поэтому разбивайте крупный экспорт на более короткие окна.

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

    Количество записей на странице, от 1 до 100. Значение от 101 до 255 возвращает 100 записей, а значение выше 255 возвращает 400.

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

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

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

    • +created_at: сначала самые старые
    • -created_at: сначала самые новые

    В URL записывайте + как %2B. Иначе + интерпретируется как пробел, и запрос возвращает 400.

  • Name
    start_time
    Type
    string
    Description

    Начало окна в формате временной метки RFC 3339, например 2026-08-01T00:00:00Z. Записи включают задачи, созданные в это время или позже. Если не указать, окно начинается за 30 дней до end_time.

    Окно может охватывать не более 366 дней. Более длинное окно возвращает 400, поэтому разбивайте более длинный экспорт на несколько окон.

  • Name
    end_time
    Type
    string
    Description

    Конец окна в формате временной метки RFC 3339. Записи включают задачи, созданные до этого времени. Если не указать, окно заканчивается в момент вашего запроса.

  • Name
    endpoints
    Type
    string
    Description

    Список эндпоинтов через запятую, которые нужно включить, с теми же именами, что и в поле endpoint. Если не указать, включаются все эндпоинты. Неизвестное имя возвращает 400.

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

    • text-to-3d: все задачи Текст в 3D, preview и refine
    • text-to-3d-preview: только задачи preview
    • text-to-3d-refine: только задачи refine
    • image-to-3d
    • multi-image-to-3d
    • retexture
    • remesh
    • convert
    • resize
    • uv-unwrap
    • rig
    • animate
    • text-to-motion
    • text-to-image
    • image-to-image
    • print-multi-color
    • print-repair
    • print-analyze
    • print-split
    • relief
  • Name
    status
    Type
    string
    Description

    Статус для включения, SUCCEEDED или FAILED. Если не указать, включаются оба. Любое другое значение возвращает 400.

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

Возвращает массив записей использования. Массив пуст, если ни одна запись не соответствует условиям.

Варианты ошибок

  • Name
    400 - Bad Request
    Description

    Один из параметров недопустим, и сообщение об ошибке указывает, какой именно. Исправьте параметр и отправьте запрос снова.

  • Name
    401 - Unauthorized
    Description

    API-ключ отсутствует или недействителен. Проверьте заголовок Authorization.

  • Name
    403 - Forbidden
    Description

    Учётная запись API-ключа не является активным участником команды Studio или Enterprise. Сообщение: This endpoint is available on Studio and Enterprise plans. Используйте API-ключ участника команды Studio или Enterprise.

  • Name
    429 - Too Many Requests
    Description

    Вы отправили слишком много запросов. Подождите количество секунд, указанное в Retry-After, затем повторите попытку.


Объект записи использования

Example usage record object

{
  "task_id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "endpoint": "image-to-3d",
  "status": "SUCCEEDED",
  "created_at": 1755787000000,
  "finished_at": 1755787045000,
  "consumed_credits": 20,
  "api_key_name": "production",
  "api_key_suffix": "a1b2",
  "metadata": {
    "user": "alex@example.com",
    "team": "fab"
  }
}
  • Name
    task_id
    Type
    string
    Description

    ID задачи — тот же ID, который вернул создавший её эндпоинт. Чтобы получить саму задачу с URL-адресами результатов, отправьте этот ID на маршрут получения соответствующего эндпоинта, например GET /openapi/v1/image-to-3d/{task_id} для записи image-to-3d.

  • Name
    endpoint
    Type
    string
    Description

    Эндпоинт, на котором выполнялась задача, например image-to-3d или rig. Задача Текст в 3D показывает свой этап: text-to-3d-preview или text-to-3d-refine.

    Более старые записи могут содержать имена отменённых эндпоинтов, которые не принимает фильтр endpoints.

  • Name
    status
    Type
    string
    Description

    Итоговый статус задачи: SUCCEEDED или FAILED.

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    Количество кредитов, потраченных на задачу, с учётом возвратов. 0 для неудавшейся задачи, поскольку Meshy возвращает кредиты, а также для бесплатной задачи, например Анализ пригодности к печати.

  • Name
    api_key_name
    Type
    string
    Description

    Имя API-ключа, с помощью которого выполнялась задача. Для задачи, выполненной через вход в приложение, это имя приложения, например Meshy CLI.

    В некоторых случаях это пустая строка, например:

    • С задачи никогда не списывались кредиты, как в случае с задачей Анализ пригодности к печати, которая бесплатна.
    • API-ключ был удалён.
    • API-ключ был создан несколько минут назад.
  • Name
    api_key_suffix
    Type
    string
    Description

    Последние четыре символа этого API-ключа, чтобы отличать ключи с одинаковым именем. Пустая строка всегда, когда api_key_name пуст, а также для входов через приложения, таких как Meshy CLI.

  • Name
    metadata
    Type
    object
    Description

    Теги, отправленные в заголовке X-Meshy-Metadata при создании задачи. {}, если их нет. См. Метаданные.