Usage API
Получайте список завершённых API-задач вашей команды и количество кредитов, потраченных на каждую из них, для экспорта данных для выставления счетов и отчётов о затратах.
Для вызова этого эндпоинта используйте API-ключ активного участника команды Studio или Enterprise. Вызвать его может любой участник, а не только владельцы и администраторы. При использовании любого другого API-ключа запрос возвращает 403.
Список записей использования
Возвращает одну страницу записей использования вашей команды, по умолчанию сначала самые новые. Без start_time и end_time записи охватывают последние 30 дней. Вызов этого эндпоинта бесплатен.
Записи включают следующие задачи:
- API-задачи, завершившиеся со статусом
SUCCEEDEDилиFAILED - Задачи всех текущих участников команды, с любых их API-ключей
- Удалённые вами задачи и задачи, у которых истёк срок хранения файлов
Записи не включают следующие задачи:
- Задачи со статусом
PENDINGилиIN_PROGRESS, а также задачи со статусомCANCELED - Задачи людей, покинувших команду
- Задачи Creative Lab
- Задачи, выполненные ИИ-агентами Meshy
- Работу, выполненную в веб-приложении Meshy
Задача появляется в записях только после завершения, в окне, соответствующем её created_at. Meshy списывает кредиты в момент создания задачи, поэтому ещё выполняющаяся задача отсутствует в записях. Прежде чем сверять записи с балансом кредитов, повторно запросите недавние окна или выполните экспорт с небольшой задержкой.
Если для вашей команды установлен период хранения данных, окно не может начинаться раньше, чем это допускает данный период.
Request
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 и refinetext-to-3d-preview: только задачи previewtext-to-3d-refine: только задачи refineimage-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- 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при создании задачи.{}, если их нет. См. Метаданные.