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
Завдання, які виконали AI-агенти 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 на маршрут отримання цієї кінцевої точки, наприклад 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 під час створення завдання. {}, якщо їх немає. Див. Metadata.