AI API 사용 방법

AI API Key 발급 방법

AI API 사용을 위해서는 GenieLabs 내 Developer Console > My Key 에서 client-id, client-key, client-secret을 발급받아야 합니다.

Parameter	Description
client-id	Signature 생성시 사용되는 사용자별 ID 식별값
client-key	API 호출 시 Header에 포함되어야 하는 Authorization Key
client-secret	Signature 생성시 사용되는 암호화 키

AI API 공통 헤더

• Request Header

Name	Description
x-client-key	클라이언트에게 발급된 client-key
x-auth-timestamp	timestamp 값 (yyyyMMDD24hhmmssSSS) (KST)
x-client-signature	client-id, client-secret, timestamp로 생성한 signature 값 (생성 방법 아래 참고)
Content-Type	API 별 tutorial 참고

• Response Header

Name	Description
Content-Type	API 별 tutorial 참고
Trx-Id	API 호출 시 생성된 Transaction ID

클라이언트 Signature 생성 방법

GenieLabs API는 발급받은 client-id 값과 client-secret 을 이용하여 signature 값을 생성하고, 이를 활용하여 인증을 수행합니다.

• Signature 값은 client-id와 timestamp 값을 이어붙인 암호화 메세지 데이터에 client-secret 값을 암호화 키로 삼아 HMAC-SHA256 알고리즘을 적용하여 생성합니다.

	구성	예시
암호화 메세지 데이터	client-id + ":" + timestamp	TEST_CLIENT_ID:20210101235959483
암호화 키	client-secret	8c1b1f08f68414d84ce31a66c2edcc2b43a72407fccc7699fd47c4ffd1b20896
Signature	(HMAC-SHA256적용)	cb40bffdf0c6a447151468df8c6a511d2b1fa0f2f030734ab668979637dce409

이 때, 생성되는 timestamp 값은 호출 시점과 시간 차가 KST 기준 1분 이내여야 합니다. 따라서 API 호출 시마다 timestamp, signature를 생성하도록 권장 드립니다.

• 각 언어별로 Signature를 생성하는 샘플 코드는 다음과 같습니다.

  • Python

  from datetime import datetime
  import hmac, hashlib
  from pytz import timezone
  
  # timestamp 생성
  timestamp = datetime.now(timezone("Asia/Seoul")).strftime("%Y%m%d%H%M%S%f")[:-3] 
   
  client_id = "TEST_CLIENT_ID";
  client_secret = "8c1b1f08f68414d84ce31a66c2edcc2b43a72407fccc7699fd47c4ffd1b20896";
  
  # HMAC 기반 signature 생성
  signature = hmac.new(
        key=client_secret.encode("UTF-8"), msg= f"{client_id}:{timestamp}".encode("UTF-8"), digestmod=hashlib.sha256
    ).hexdigest()

  • Java

  import javax.crypto.Mac;
  import javax.crypto.spec.SecretKeySpec;
  
  # timestamp 생성 함수
  public string getTimeStamp() {
    SimpleDateFormat simpleDateFormat= new SimpleDateFormat("yyyyMMddHHmmssSSS");
    Date today = new Date();
    String timestamp = simpleDateFormat.format(today);
    return timestamp;
  }
  
  # HMAC 기반 Signature 생성 함수
  public String makeSignature(String timestamp, String client_id, String client_secret) {
    String digest = null;
    try {
      SecretKeySpec key = new SecretKeySpec((client_secret).getBytes("UTF-8"), "HmacSHA256");
      Mac mac = Mac.getInstance("HmacSHA256");
      mac.init(key);
      String digestTarget = client_id + ":" +timestamp;
      byte[] bytes = mac.doFinal(digestTarget.getBytes("ASCII"));
      StringBuffer hash = new StringBuffer();
      for(int i = 0; i < bytes.length; i++) {
      	String hex = Integer.toHexString(0xFF & bytes[i]);
        if(hex.length() == 1) hash.append('0');
        hash.append(hex);
      }
      digest = hash.toString();
    } catch(Exception e) {
      e.printStackTrace();
    }
    return digest;
  }
  
  public void signatureTest() {
    String client_id = "TEST_CLIENT_ID";
    String timestamp = getTimeStamp(); 
    String client_secret = "8c1b1f08f68414d84ce31a66c2edcc2b43a72407fccc7699fd47c4ffd1b20896";
  	System.out.println("Signature:"+ makeSignature (client_id, timestamp, client_secret));
  }

  • Node.js

  var crypto = require("crypto"); 
  
  # timestamp 생성
  var dateFormat = require("dateformat"); 
  var now = new Date();
  var timestamp = dateFormat(now, "yyyymmddHHMMssl"); #yyyymmddHHMMssl 포맷으로 timestamp 생성
  
  var clientID = "TEST_CLIENT_ID";
  var clientSecret = "8c1b1f08f68414d84ce31a66c2edcc2b43a72407fccc7699fd47c4ffd1b20896";
  
  # HMAC 기반 signature 생성
  var signature = crypto.createHmac("sha256", clientSecret).update(clientID + ":" + timestamp).digest("hex");
  console.log(signature) 

  • Objective-C

  #import <CommonCrypto/CommonCrypto.h>
  
  # Timestamp 생성 함수
  - (NSString*)getTimeStamp{
    NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
    [dateFormatter setDateFormat:@"yyyyMMddhhmmssSSS"];
    NSString *newDate = [dateFormatter stringFromDate:[NSDate date]];
    return newDate;
  }
  
  # HMAC 기반 Signature 생성 함수
  - (NSString*)makeSignature:(NSString *)clientSecret
              clientId:(NSString *)clientId
              timestamp:(NSString *)timestamp {
    NSString *data = [NSString stringWithFormat:@"%@:%@",clientId,timestamp];
    const char *cKey = [clientSecret cStringUsingEncoding:NSASCIIStringEncoding];
    const char *cData = [data cStringUsingEncoding:NSASCIIStringEncoding];
    unsigned char cHMAC[CC_SHA256_DIGEST_LENGTH];
    CCHmac(kCCHmacAlgSHA256, cKey, strlen(cKey), cData, strlen(cData), cHMAC);
  
    NSString * signature = @"";
    for(int i=0;i<CC_SHA256_DIGEST_LENGTH;i++) {
      NSString *hex = [NSString stringWithFormat:@"%X",(0xFF & cHMAC[i])];
      if(hex.length == 1)
      signature = [signature stringByAppendingString:@"0"];
      signature = [signature stringByAppendingString:hex];
    }
    signature = [signature lowercaseString];
    // NSLog(@"signature : %@",signature);
  
  	return signature;
  }

Rest API Response Status Code

API 상태 응답 코드는 다음과 같습니다.

Status Code	Description
200	요청 성공
301	서비스 유형 전환에 따른 AI API Serving 서비스 URL 변경 Response Body에 URL 코드 전달
400	파라미터 설정 오류(파라미터, 멀티파트 등)
401	권한 없음 (인증 오류) x-client-key / x-client-signature / x-auth-timestamp 누락, x-client-key 인증 실패, x-auth-timestamp 포맷 오류 또는 만료, x-client-signature 인증 실패 등
429	사용량 제한 초과 (일 호출 건 수 초과)
500	시스템 에러