URL 단축
보안/안전 서비스 중긴 원본 URL을 짧고 간결한 URL로 변환해 줍니다.
API 키 필수
HTTPS
POST
/api/v1/url/shorten
API 설명
복잡하고 긴 URL을 짧고 기억하기 쉬운 다섯 자리 코드로 변환하여 관리 효율성을 높여 줍니다.
- 실시간 클릭 분석이 용이한 짧은 주소 제공
- 마케팅 캠페인, SNS 공유, 문자 메시지에 최적화
- 중복 생성 방지 및 효율적인 코드 관리
사용 가이드
## 사용 방법
### 요청
```http
POST /api/v1/url/shorten
Content-Type: application/json
X-API-Key: YOUR_API_KEY
```
### 요청 파라미터
| 필드명 | 타입 | 필수 | 설명 |
| :--- | :---: | :---: | :--- |
| url | String | Y | 단축할 원본 URL (http:// 또는 https:// 포함) |
| check_harmful | Boolean | N | true 설정 시 AI가 악성·스팸·도박·성인 등 유해 여부를 사전 분석합니다. 유해 URL이면 단축이 거부됩니다. (처리 시간 추가 소요, "유해 URL 탐지" API 구독 필요) |
### 응답 결과 (기본 - 성공)
```json
{
"success": true,
"short_url": "https://ai-engines.kr/a1B2c",
"api": "url-shortener",
"remaining": 99
}
```
### 응답 결과 (유해 탐지 옵션 사용 시 - 안전 URL)
```json
{
"success": true,
"short_url": "https://ai-engines.kr/a1B2c",
"api": "url-shortener",
"remaining": 99,
"safety_check": {
"is_malicious": false,
"category": "safe",
"reason": "유해 요소가 발견되지 않았습니다.",
"remaining": 98
}
}
```
### 오류 응답 결과 (유해 URL 거부 - 422)
```json
{
"success": false,
"code": 422,
"error": "유해 URL로 탐지되어 단축 URL 생성이 거부되었습니다.",
"is_malicious": true,
"category": "gambling",
"reason": "도박 관련 키워드 및 콘텐츠가 다수 포함되어 있습니다.",
"remaining": 97
}
```
### 오류 응답 결과 (유해 탐지 API 미구독 - 403)
```json
{
"success": false,
"code": 403,
"error": "check_harmful 옵션을 사용하려면 \"유해 URL 탐지\" API를 먼저 신청해야 합니다."
}
```
### 오류 응답 결과 (URL 형식 오류 - 400)
```json
{
"success": false,
"code": 400,
"error": "유효한 URL을 입력해주세요."
}
```
### 오류 코드
| 코드 | 메시지 | 원인 및 해결 방법 |
| :--- | :--- | :--- |
| **400** | 유효한 URL을 입력해주세요. | URL 형식이 잘못되었거나 비어있습니다. |
| **401** | 유효하지 않은 API 키입니다. | API 키 인증에 실패했습니다. |
| **403** | check_harmful 옵션을 사용하려면 "유해 URL 탐지" API를 먼저 신청해야 합니다. | check_harmful 사용 시 url-detection API 구독이 필요합니다. |
| **422** | 유해 URL로 탐지되어 단축 URL 생성이 거부되었습니다. | check_harmful 옵션 사용 시 유해 URL로 판정된 경우입니다. |
| **429** | 사용 가능 횟수를 모두 소진하였습니다. | 서비스 호출 할당량을 초과했습니다. |
공통 인증 헤더
X-API-Key: YOUR_API_KEY
Content-Type: application/jsoncURL 예제
curl -X POST https://engines.ai.kr/api/v1/url/shorten \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https:\/\/example.com\/very-long-url-to-shorten","check_harmful":false}'