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

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

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