Usage API

Usage API возвращает историю выполненных API-задач вашей команды с указанием кредитов, потраченных на каждую из них. Фильтруйте по временному диапазону, эндпоинту или статусу и листайте страницы результатов для массового экспорта.

Доступность. API-ключ должен принадлежать команде тарифа Studio или Enterprise; ключи на любом другом тарифе, а также ключи без команды, получат ответ 403.

GET/openapi/v1/usage/tasks

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

Возвращает одну страницу API-задач команды, начиная с самых новых. Если явный временной диапазон не указан, ответ охватывает последние 30 дней.

Параметры

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

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

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

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

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

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

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

    • +created_at: сортировка по времени создания в порядке возрастания.
    • -created_at: сортировка по времени создания в порядке убывания.
  • Name
    start_time
    Type
    string
    Description

    Начало временного диапазона created_at, в формате временной метки RFC 3339 (например, 2026-08-01T00:00:00Z). По умолчанию — 30 дней до end_time. Диапазон может охватывать не более 1 года — для более крупных экспортов листайте страницы по последовательным диапазонам.

  • Name
    end_time
    Type
    string
    Description

    Конец временного диапазона created_at, в формате временной метки RFC 3339. По умолчанию — текущее время.

  • Name
    endpoints
    Type
    string
    Description

    Список имён эндпоинтов через запятую, которые нужно включить. Принимает те же значения, что несёт поле ответа endpoint, — text-to-3d, text-to-3d-preview, text-to-3d-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 — где text-to-3d является общим значением, охватывающим и фазу preview, и фазу refine. Опустите параметр, чтобы включить все эндпоинты.

  • Name
    status
    Type
    string
    Description

    Фильтр по конечному статусу задачи: SUCCEEDED или FAILED. Опустите параметр, чтобы включить оба статуса.

Возвращает

Возвращает постраничный список объектов записи об использовании.

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

Команды с настроенной политикой хранения данных получают записи в пределах своего настроенного окна хранения.

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"
  },
  {
    "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"
  }
]

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

  • Name
    task_id
    Type
    string
    Description

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

  • Name
    endpoint
    Type
    string
    Description

    Эндпоинт, на котором выполнялась задача, например image-to-3d или text-to-3d-refine. Задачи Текст в 3D сообщают свою фазу (text-to-3d-preview / text-to-3d-refine).

  • Name
    status
    Type
    string
    Description

    Конечный статус задачи: SUCCEEDED или FAILED.

  • Name
    created_at
    Type
    timestamp
    Description

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

  • Name
    finished_at
    Type
    timestamp
    Description

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

  • Name
    consumed_credits
    Type
    integer
    Description

    Кредиты, потраченные на эту задачу. Для задач со статусом FAILED возвращает 0 (при неудаче кредиты возвращаются).

  • Name
    api_key_name
    Type
    string
    Description

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

  • Name
    api_key_suffix
    Type
    string
    Description

    Последние четыре символа этого API-ключа, для различения ключей с одинаковым именем.

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