Usage API
청구 내역 추출과 비용 보고서 작성을 위해, 팀의 완료된 API 작업과 각 작업에서 사용한 크레딧을 조회합니다.
이 엔드포인트를 호출하려면 Studio 또는 Enterprise 팀의 활성 멤버의 API 키를 사용하세요. 소유자와 관리자뿐 아니라 어떤 멤버든 호출할 수 있습니다. 그 외의 API 키로 요청하면 403이 반환됩니다.
사용 기록 목록 조회
기본적으로 최신순으로 정렬된 팀 사용 기록 한 페이지를 반환합니다. start_time과 end_time을 지정하지 않으면 기록은 지난 30일간의 내용을 포함합니다. 이 엔드포인트 호출은 무료입니다.
기록에는 다음 작업이 포함됩니다:
SUCCEEDED또는FAILED로 완료된 API 작업- 팀의 현재 모든 멤버의 작업(그들의 어떤 API 키로 수행되었든 포함)
- 삭제한 작업과 파일이 만료된 작업
기록에는 다음 작업이 포함되지 않습니다:
- 아직
PENDING또는IN_PROGRESS상태인 작업, 그리고CANCELED상태인 작업 - 팀을 떠난 사람의 작업
- Creative Lab 작업
- Meshy의 AI 에이전트가 실행한 작업
- Meshy 웹 앱에서 수행한 작업
작업은 완료된 후에야 해당 작업의 created_at 시점이 포함된 기간 범위에 기록으로 나타납니다. Meshy는 작업을 생성할 때 크레딧을 차감하므로, 아직 실행 중인 작업은 기록에 나타나지 않습니다. 기록과 크레딧 잔액을 대조하기 전에, 최근 기간을 다시 조회하거나 약간의 지연 후 내보내기를 수행하세요.
팀에 데이터 보존 기간이 설정되어 있다면, 조회 범위는 해당 기간이 허용하는 시점 이전으로는 시작할 수 없습니다.
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",
"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). 기록에는 이 시점 이후에 생성된 작업이 포함됩니다. 생략하면end_time기준 30일 전부터 기간이 시작됩니다.조회 기간은 최대 366일까지 지정할 수 있습니다. 이보다 긴 기간을 지정하면
400이 반환되므로, 더 긴 내보내기는 여러 기간으로 나누어 수행하세요.
- Name
- end_time
- Type
- string
- Description
조회 기간의 종료 시점으로, RFC 3339 타임스탬프 형식입니다. 기록에는 이 시점 이전에 생성된 작업이 포함됩니다. 생략하면 요청 시점이 조회 기간의 종료 시점이 됩니다.
- Name
- endpoints
- Type
- string
- Description
포함할 엔드포인트를
endpoint필드와 동일한 이름으로, 쉼표로 구분하여 나열합니다. 생략하면 모든 엔드포인트가 포함됩니다. 알 수 없는 이름을 지정하면400이 반환됩니다.사용 가능한 값:
text-to-3d: preview와 refine을 포함한 모든 텍스트로 3D 작업text-to-3d-preview: preview 작업만text-to-3d-refine: refine 작업만image-to-3dmulti-image-to-3dretextureremeshconvertresizeuv-unwrapriganimatetext-to-motiontext-to-imageimage-to-imageprint-multi-colorprint-repairprint-analyzeprint-splitrelief
- 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입니다. Studio 또는 Enterprise 팀 멤버의 API 키를 사용하세요.
- 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와 동일합니다. 출력 URL을 포함한 작업 자체를 조회하려면 해당 ID를 해당 엔드포인트의 조회 경로로 보내세요. 예를 들어
image-to-3d기록의 경우GET /openapi/v1/image-to-3d/{task_id}를 사용합니다.
- 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
작업이 생성된 시각으로, 유닉스 밀리초 단위입니다.
- Name
- finished_at
- Type
- timestamp
- Description
작업이 완료된 시각으로, 유닉스 밀리초 단위입니다. 작업에 완료 시각이 없으면
null입니다.
- Name
- consumed_credits
- Type
- integer
- Description
해당 작업이 사용한 크레딧 수로, 환불 이후의 값입니다. 실패한 작업은 Meshy가 환불 처리하므로
0이며, Analyze Printability처럼 무료인 작업도0입니다.
- Name
- api_key_name
- Type
- string
- Description
해당 작업을 실행한 API 키의 이름입니다. 앱 로그인으로 실행된 작업의 경우 앱 이름이며, 예를 들어
Meshy CLI입니다.다음과 같은 경우에는 빈 문자열입니다:
- Analyze Printability 작업처럼 무료라서 과금된 적이 없는 작업
- API 키가 삭제된 경우
- API 키가 최근 몇 분 이내에 생성된 경우
- Name
- api_key_suffix
- Type
- string
- Description
같은 이름을 가진 키를 구분하기 위한 해당 API 키의 마지막 네 글자입니다.
api_key_name이 비어 있을 때와, Meshy CLI 같은 앱 로그인의 경우 빈 문자열입니다.
- Name
- metadata
- Type
- object
- Description
작업이 생성될 때
X-Meshy-Metadata헤더로 전송된 태그입니다. 없으면{}입니다. Metadata를 참고하세요.