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
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 при создании задачи. {}, если таковых нет. См. Метаданные.