Usage API
Usage API는 팀의 과거 API 작업 내역과 각 작업에서 소비된 크레딧을 반환합니다. 시간 범위, 엔드포인트 또는 상태로 필터링하고, 결과를 페이지네이션하여 대량으로 내보낼 수 있습니다.
이용 가능 대상. API 키는 Studio 또는 Enterprise 팀에 속해야 합니다. 다른 요금제의 키 또는 팀이 없는 키는 403을 받습니다.
사용량 기록 조회
팀의 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). 기본값은end_time으로부터 30일 전입니다. 범위는 최대 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
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"
}