lowpoly는 2026. 10. 30.에 지원 종료됩니다. 3D 생성 모델 meshy-7은 2026. 12. 31.에 지원 종료됩니다. 텍스처 모델로는 계속 사용할 수 있습니다. 요청 오류를 피하려면 해당 날짜 전에 모델을 전환하세요. 모든 지원 중단 보기

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

    조회 기간의 시작 시점으로, 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-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
    • relief
  • 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를 참고하세요.