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