한 키로 시작하기

API 기본 주소

현재 접속한 HANKIRO 주소 뒤에 /api/v1을 붙입니다. 아래 예제의 $SITE_URL에는 사용 중인 HANKIRO 주소를 넣으세요.

인증

키 페이지에서 발급한 Bearer 키를 붙입니다. 실제 키 값을 문서에 적지 마세요.

Authorization: Bearer mh_live_...

허용 IP 제한

키를 발급할 때 호출 서버의 정확한 IPv4 또는 IPv6 주소를 최대 16개 등록할 수 있습니다. 비워두면 모든 IP에서 호출할 수 있으며, CIDR 대역 표기는 지원하지 않습니다. 발급 후에는 목록을 바꿀 수 없으므로 변경이 필요하면 새 키를 발급한 뒤 기존 키를 폐기하세요.

허용 목록과 호출 주소가 다르면 403 IP_NOT_ALLOWED, 신뢰할 수 있는 호출자 IP를 확인할 수 없으면 503 CLIENT_IP_UNAVAILABLE을 반환합니다.

분당 API 요청 한도

키에 설정한 분당 한도는 그 키로 인증된 모든 Bearer 요청에 적용됩니다. 실행 요청뿐 아니라 입력 오류, 같은 멱등 키의 재요청, 충돌 응답, 작업 상태 조회도 각각 한 번의 요청으로 계산합니다. 로그인 세션으로 보낸 요청은 API 키 한도에 포함되지 않습니다.

한도를 넘으면 429 RATE_LIMITED와 Retry-After 헤더가 반환됩니다. 헤더가 안내하는 시간 이후에 호출 빈도를 낮춰 다시 요청하세요. 키의 한도를 0으로 설정하면 분당 제한 없이 요청 수만 기록합니다.

API 키 보안 활동

키 페이지에서 최근 30일 동안의 키 발급·폐기, IP 차단, 호출자 IP 확인 실패, 요청 한도 초과를 확인할 수 있습니다. 같은 키에서 같은 종류로 발생한 활동은 분 단위로 묶어 횟수와 함께 표시하며, 호출자 IP는 전체 주소 대신 일부만 마스킹해 보여줍니다.

선불 예약과 자동 정산

실행 직전에는 표시된 예상 금액이 사용 가능 잔액에서 예약됩니다. 결과가 확정되면 실제 사용액으로 정산되고, 공급사가 호출 전에 명시적으로 거절한 요청은 예약이 해제됩니다. 클라이언트가 작업 조회를 멈춰도 접수 번호가 있는 작업과 저장된 결과는 백그라운드에서 계속 확인합니다.

네트워크 단절처럼 공급사 접수 여부를 확정할 수 없는 경우에는 중복 실행이나 잘못된 환불을 막기 위해 예약을 즉시 해제하지 않습니다. UPSTREAM_INDETERMINATE가 오면 새 요청을 만들지 말고, 기존 task_uuid를 조회하거나 같은 본문과 같은 Idempotency-Key로 상태를 확인하세요.

미디어 실행

영상 생성은 수분이 걸릴 수 있으므로 queued 또는 processing 동안 지수 백오프로 작업을 조회하세요. 완료된 영상은 output.video.url의 private signed URL로 반환됩니다. 주소는 1시간 뒤 만료되므로 URL 자체를 장기 저장하지 말고 task_uuid를 다시 조회해 새 주소를 받으세요.

POST $SITE_URL/api/v1/run/google/veo3.1/text-to-video
Authorization: Bearer mh_live_...
Idempotency-Key: unique-request-key
{ "input": { "prompt": "..." } }

GET $SITE_URL/api/v1/run/tasks/{task_uuid}

LLM

GET $SITE_URL/api/v1/llm/models
Authorization: Bearer mh_live_...

POST $SITE_URL/api/v1/llm/v1/chat/completions
Authorization: Bearer mh_live_...
Idempotency-Key: unique-request-key
{ "model": "gemini-3.1-flash-lite", "messages": [{"role":"user","content":"안녕"}] }

{
  "error": {
    "code": "MODEL_NOT_CONNECTED",
    "message": "이 모델은 카탈로그에 있지만 현재 호출 연결 대상이 아닙니다."
  }
}

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "사용 가능한 선불 원화 잔액이 부족합니다."
  },
  "currency": "KRW",
  "available_krw": 1200,
  "required_krw": 1800,
  "shortfall_krw": 600
}