lowpoly는 2026. 10. 30.에 지원 종료됩니다. 요청 오류를 피하려면 해당 날짜 전에 모델을 전환하세요. 모든 지원 중단 보기

Usage API

청구 내역 추출과 비용 보고서를 위해, 팀의 완료된 API 작업과 각 작업이 사용한 크레딧을 조회합니다.

이 엔드포인트를 호출하려면 Studio 또는 Enterprise 팀의 활성 멤버의 API 키를 사용하세요. 소유자와 관리자뿐 아니라 모든 멤버가 호출할 수 있습니다. 그 외의 API 키로 요청하면 403이 반환됩니다.

GET/openapi/v1/usage/tasks

사용 기록 목록 조회

기본적으로 최신순으로 정렬된 팀의 사용 기록 한 페이지를 반환합니다. start_time과 end_time을 지정하지 않으면 기록은 최근 30일 동안의 내용을 포함합니다. 이 엔드포인트 호출은 무료입니다.

기록에는 다음 작업이 포함됩니다:

  • SUCCEEDED 또는 FAILED로 완료된 API 작업
  • 현재 팀에 속한 모든 멤버의 작업(어느 API 키로 실행했든 상관없이)
  • 삭제한 작업, 그리고 파일이 만료된 작업

기록에는 다음 작업이 제외됩니다:

  • 아직 PENDING 또는 IN_PROGRESS 상태인 작업, 그리고 CANCELED 작업
  • 팀을 떠난 사용자의 작업
  • Creative Lab 작업
  • Meshy의 AI 에이전트가 실행한 작업
  • Meshy 웹 앱에서 수행한 작업

작업은 완료된 후에만, created_at 기준 시간 범위 안에서 기록에 나타납니다. Meshy는 작업을 생성할 때 크레딧을 차감하므로, 아직 실행 중인 작업은 기록에 나타나지 않습니다. 크레딧 잔액과 기록을 대조하기 전에, 최근 기간을 다시 조회하거나 약간의 지연 후에 내보내기를 진행하세요.

팀에 데이터 보존 기간이 설정되어 있다면, 조회 기간은 해당 기간이 허용하는 범위보다 더 과거로 시작할 수 없습니다.

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

    조회 기간의 시작 시점으로, 예를 들어 2026-08-01T00:00:00Z와 같은 RFC 3339 타임스탬프입니다. 이 시간 이후에 생성된 작업이 기록에 포함됩니다. 생략하면 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-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
    • print-split
  • 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을 포함한 작업 자체를 가져오려면, 예를 들어 image-to-3d 기록의 경우 GET /openapi/v1/image-to-3d/{task_id}와 같이 해당 엔드포인트의 조회 경로로 이 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이며, 프린팅 가능성 분석과 같은 무료 작업도 0입니다.

  • Name
    api_key_name
    Type
    string
    Description

    작업을 실행한 API 키의 이름입니다. 앱 로그인으로 실행된 작업의 경우, 예를 들어 Meshy CLI와 같이 앱의 이름이 표시됩니다.

    다음과 같은 경우 빈 문자열이 됩니다:

    • 프린팅 가능성 분석 작업처럼 무료라서 요금이 전혀 청구되지 않은 작업
    • API 키가 삭제된 경우
    • API 키가 생성된 지 몇 분 이내인 경우
  • Name
    api_key_suffix
    Type
    string
    Description

    이름이 같은 키를 구분하기 위한 해당 API 키의 마지막 네 글자입니다. api_key_name이 빈 문자열일 때, 그리고 Meshy CLI와 같은 앱 로그인의 경우에는 빈 문자열입니다.

  • Name
    metadata
    Type
    object
    Description

    작업 생성 시 X-Meshy-Metadata 헤더로 전송된 태그입니다. 없으면 {}입니다. Metadata를 참고하세요.