개요

API 키로 문서·이미지 처리 API를 호출하거나, 계정의 잔액·사용 내역·적용 단가를 조회할 수 있습니다. 문서·이미지 처리 API의 요청 형식은 좌측 API 레퍼런스에서 확인하세요.

시작하기

1. 회원가입 후 로그인합니다.
2. 대시보드 → API 키에서 키(pk_live_…)를 발급합니다. 키 원문은 발급 시 한 번만 표시됩니다.
3. 아래 요청 예시의 YOUR_API_KEY를 발급한 키로 바꿔 호출합니다.

인증

모든 요청의 x-api-key 헤더에 API 키를 넣습니다. 조회할 계정은 이 키로 자동 확인하므로 사용자 ID를 따로 보내지 않습니다.

x-api-key: YOUR_API_KEY

키가 없거나 유효하지 않으면 401 invalid_key가 반환됩니다. 폐기된 키와 이용 정지 계정의 키도 사용할 수 없습니다.

과금

• 문서·이미지 처리 API는 계정별 무료 제공량을 먼저 사용하고, 소진 후에는 충전 잔액에서 사용 금액을 차감합니다.
• 처리 실패로 환불되는 경우에는 차감한 금액을 잔액으로 돌려드립니다.
• 단가와 사용 금액은 원화이며 부가세 별도입니다. 실제 과금에는 호출 시점의 단가가 적용됩니다.
• 아래 잔액 조회·사용 내역 조회·API별 단가 조회는 무료이며, 충전 잔액과 무료 제공량을 소모하지 않습니다.

충전 잔액 조회

API 사용에 쓸 수 있는 현재 충전 잔액을 확인합니다. 같은 계정에서 발급한 키는 모두 같은 잔액을 조회합니다.

GET /api/v1/balance

요청

curl "https://marketapi.nadoo.ai/api/v1/balance" \
  -H "x-api-key: YOUR_API_KEY"

응답 예시

{
  "balanceKrw": 49800,
  "lowBalanceThresholdKrw": 5000,
  "updatedAt": "2026-08-06T02:31:00.000Z"
}

사용 내역 조회

대시보드의 사용량 화면에 표시되는 API 사용 내역(차감)과 그 사용 건에 대한 환불을 최신순으로 가져옵니다. 무료로 사용한 내역도 포함됩니다. type으로 차감 또는 환불만 골라 볼 수 있습니다. 잔액 충전은 사용 내역이 아니므로 포함하지 않습니다.

조회에 사용한 키의 호출만이 아니라, 같은 계정의 모든 API 키로 사용한 내역을 반환합니다.

GET /api/v1/usage

1. 첫 페이지 요청

아래 예시는 한 페이지에 최대 20건을 요청합니다.

curl "https://marketapi.nadoo.ai/api/v1/usage?page=1&pageSize=20" \
  -H "x-api-key: YOUR_API_KEY"

2. 응답 읽기

아래는 내역이 2건 있는 계정의 응답 예시입니다. 20건을 요청해도 남은 내역이 2건이면 2건만 반환됩니다.

{
  "items": [{
    "id": "usage_example_1",
    "type": "CHARGE",
    "deltaKrw": -200,
    "createdAt": "2026-08-06T02:31:00.000Z",
    "productSlug": "hira-detect",
    "productName": "멀티 제약사 라벨링",
    "unitPriceKrw": 200,
    "free": false,
    "requestId": "request_example_1"
  }, {
    "id": "usage_example_0",
    "type": "REFUND",
    "deltaKrw": 200,
    "createdAt": "2026-08-05T01:00:00.000Z",
    "productSlug": "hira-detect",
    "productName": "멀티 제약사 라벨링",
    "unitPriceKrw": 200,
    "free": false,
    "requestId": "request_example_0:refund"
  }],
  "page": 1,
  "pageSize": 20,
  "hasMore": false
}

첫 번째는 멀티 제약사 라벨링 API를 사용해 200원이 차감된 내역이고, 두 번째는 이전 사용 건이 처리 실패로 200원 환불된 내역입니다. hasMore: false이므로 추가 페이지를 요청할 필요가 없습니다.

3. 다음 페이지 요청

응답의 hasMore가 true일 때만 page를 1 늘려 다시 호출합니다. pageSize는 같은 값으로 유지하세요.

curl "https://marketapi.nadoo.ai/api/v1/usage?page=2&pageSize=20" \
  -H "x-api-key: YOUR_API_KEY"

조회 시 알아둘 점

• 전체 건수·전체 페이지 수·금액 합계는 제공하지 않습니다. 다음 페이지가 필요한지는 hasMore로 판단합니다.
• 내역이 없는 페이지를 요청하면 items: [], hasMore: false를 반환합니다.
• 사용 금액만 보려면 type=CHARGE로 조회하세요. 이 경우 unitPriceKrw 합이 사용액(부가세 별도)입니다. 나중에 환불된 사용 건도 최초 차감 금액으로 남고 환불은 별도 REFUND 행으로 기록됩니다.
• 충전 내역은 포함하지 않습니다. 이 목록의 금액을 더해 현재 잔액을 계산하면 안 됩니다. 현재 잔액은 잔액 조회 API를 사용하세요.
• 여러 페이지를 가져오는 도중 새 사용 내역이 생기면 항목이 다음 페이지로 밀려 중복될 수 있습니다. 목록을 합칠 때는 id로 중복을 제거하세요.

API별 단가 조회

내 계정에 적용되는 API별 현재 단가를 가져옵니다. 고객 서비스에서 API 가격을 표시하거나, 사용 전 단가를 확인할 때 사용하세요.

GET /api/v1/catalog

요청

조회 조건은 필요하지 않습니다. API 키만 보내면 됩니다.

curl "https://marketapi.nadoo.ai/api/v1/catalog" \
  -H "x-api-key: YOUR_API_KEY"

응답 예시

{
  "currency": "KRW",
  "vatIncluded": false,
  "items": [{
    "slug": "hira-detect",
    "name": "멀티 제약사 라벨링",
    "billingUnit": "CALL",
    "priceKrw": 200
  }]
}

이 예시는 내 계정에서 멀티 제약사 라벨링 API의 1건당 단가가 200원(부가세 별도)이라는 뜻입니다. 무료 제공량이 남아 있으면 실제 호출 시에는 무료 제공량을 먼저 사용합니다.

단가를 사용할 때

• 계정에 별도로 설정된 단가가 있으면 그 금액을 반환합니다. 별도 설정이 없으면 기본 단가를 반환하므로, 고객 서비스에서 할인 계산을 할 필요가 없습니다.
• priceKrw: null은 무료가 아닙니다. 화면에는 “가격 문의” 등으로 표시하고, 단가 설정 후 이용하세요.
• 조회 후 단가가 변경될 수 있습니다. 실제 차감에는 API를 호출하는 시점의 단가가 적용되며, 이미 사용한 금액은 사용 내역 조회에서 확인합니다.

공통 에러

에러 응답 본문: { "error": "<code>", "message"?: "..." }

요청 한도와 재시도

• 요청 한도는 API 키 단위로 적용됩니다. 한도는 처리 상황에 따라 달라질 수 있으니 고정값에 맞추지 말고 응답 헤더 RateLimit-Limit·RateLimit-Remaining·RateLimit-Reset(초)으로 남은 한도를 확인할 수 있습니다.
• 429·503 응답에는 Retry-After(초) 헤더가 있습니다. 그 시간만큼 기다린 뒤, 반복 실패 시 지수 백오프(+무작위 지연)로 간격을 늘려 재시도하세요.
• 재시도할 때는 같은 Idempotency-Key와 같은 본문을 보내세요. 이미 처리된 요청이면 재처리·재과금 없이 최초 결과가 돌아옵니다. 본문을 바꾸면 새 키를 써야 합니다(422).
• 400·402·413·415·422는 재시도해도 결과가 같습니다. 요청을 고친 뒤 다시 보내세요.
• 성공 응답에 warnings가 있으면 결과를 확인해 주세요. 예: image_truncated — 파일이 잘렸거나 손상된 것으로 보여 일부 내용이 누락됐을 수 있습니다.
• 여러 장을 처리할 때는 단건 API를 동시에 많이 호출하지 말고 배치 API(detect-batch, *-batch-async)를 사용하세요.