Data Images RESTful API v2

API RESTful để quản lý hình ảnh với đầy đủ các chức năng CRUD, tải lên, tìm kiếm và lấy ngẫu nhiên.

Base URL

https://kkdemo.kkwebsite.com/api/v2/data-images

Authentication

API sử dụng Bearer token authentication. Token phải được gửi trong header:

Authorization: Bearer {your_token}

1. Lấy Danh Sách Hình Ảnh

Mô tả

Lấy danh sách tất cả hình ảnh với phân trang và các bộ lọc.

Endpoint, Method, Authentication

GET https://kkdemo.kkwebsite.com/api/v2/data-images

Authentication: Bearer token

Authorization: Bearer YOUR_TOKEN_HERE

Tham số (query)

Tên	Kiểu	Bắt buộc	Mô tả
page	Integer	Không	Số trang (mặc định: 1)
limit	Integer	Không	Số lượng mỗi trang (mặc định: 40)
category_id	Integer	Không	Lọc theo category ID
approve	Integer	Không	Lọc theo trạng thái approve (0/1)
search	String	Không	Tìm kiếm theo tên file

Code Example

CURL Example

curl -X GET "https://kkdemo.kkwebsite.com/api/v2/data-images?page=1&limit=20&category_id=1&approve=1" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

N8N Example

Cấu hình HTTP Request Node:

• URL: https://kkdemo.kkwebsite.com/api/v2/data-images
• Method: GET
• Headers:

  Authorization: Bearer YOUR_TOKEN_HERE

• Query Parameters:

  page: 1
  limit: 20
  category_id: 1
  approve: 1

PHP Example

function getImages($token, $page = 1, $limit = 20, $categoryId = null, $approve = null) {
    $url = 'https://kkdemo.kkwebsite.com/api/v2/data-images';
    $params = [
        'page' => $page,
        'limit' => $limit
    ];
    
    if ($categoryId !== null) $params['category_id'] = $categoryId;
    if ($approve !== null) $params['approve'] = $approve;
    
    $url .= '?' . http_build_query($params);
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Sử dụng
$result = getImages('YOUR_TOKEN_HERE', 1, 20, 1, 1);

Python Example

import requests

def get_images(token, page=1, limit=20, category_id=None, approve=None):
    url = 'https://kkdemo.kkwebsite.com/api/v2/data-images'
    headers = {'Authorization': f'Bearer {token}'}
    params = {'page': page, 'limit': limit}
    
    if category_id is not None:
        params['category_id'] = category_id
    if approve is not None:
        params['approve'] = approve
    
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Sử dụng
result = get_images('YOUR_TOKEN_HERE', page=1, limit=20, category_id=1, approve=1)

Response

Success Response

{
    "status": "success",
    "data": [
        {
            "id": 1,
            "file_name": "abc123.jpg",
            "category_id": 1,
            "original_name": "image.jpg",
            "file_size": 1024000,
            "file_type": "image/jpeg",
            "width": 1920,
            "height": 1080,
            "approve": 1,
            "used": 5,
            "created_at": "2024-01-01 10:00:00",
            "updated_at": "2024-01-01 10:00:00",
            "url": "https://kkdemo.kkwebsite.com/image/images/20240101/abc123.jpg"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 40,
        "total": 100,
        "total_pages": 3
    }
}

Error Response

{
    "code": "UNAUTHORIZED",
    "message": "Token không hợp lệ"
}

2. Lấy Chi Tiết Hình Ảnh

Mô tả

Lấy thông tin chi tiết của một hình ảnh theo ID.

Endpoint, Method, Authentication

GET https://kkdemo.kkwebsite.com/api/v2/data-images/{id}

Authentication: Bearer token

Authorization: Bearer YOUR_TOKEN_HERE

Tham số (path)

Tên	Kiểu	Bắt buộc	Mô tả
id	Integer	Có	ID của hình ảnh

Code Example

CURL Example

curl -X GET https://kkdemo.kkwebsite.com/api/v2/data-images/1 \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

N8N Example

Cấu hình HTTP Request Node:

• URL: https://kkdemo.kkwebsite.com/api/v2/data-images/1
• Method: GET
• Headers:

  Authorization: Bearer YOUR_TOKEN_HERE

PHP Example

function getImageById($id, $token) {
    $url = "https://kkdemo.kkwebsite.com/api/v2/data-images/{$id}";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Sử dụng
$result = getImageById(1, 'YOUR_TOKEN_HERE');

Python Example

import requests

def get_image_by_id(image_id, token):
    url = f'https://kkdemo.kkwebsite.com/api/v2/data-images/{image_id}'
    headers = {'Authorization': f'Bearer {token}'}
    response = requests.get(url, headers=headers)
    return response.json()

# Sử dụng
result = get_image_by_id(1, 'YOUR_TOKEN_HERE')

Response

Success Response

{
    "status": "success",
    "data": {
        "id": 1,
        "file_name": "abc123.jpg",
        "file_size": 1024000,
        "file_type": "image/jpeg",
        "category_id": 1,
        "original_name": "image.jpg",
        "width": 1920,
        "height": 1080,
        "approve": 1,
        "used": 5,
        "created_at": "2024-01-01 10:00:00",
        "updated_at": "2024-01-01 10:00:00",
        "url": "https://kkdemo.kkwebsite.com/image/images/20240101/abc123.jpg"
    }
}

Error Response

{
    "code": "NOT_FOUND",
    "message": "Không tìm thấy hình ảnh"
}

3. Tải Lên Hình Ảnh

Mô tả

Tải lên hình ảnh mới từ file hoặc URL.

Endpoint, Method, Authentication

POST https://kkdemo.kkwebsite.com/api/v2/data-images

Authentication: Bearer token

Authorization: Bearer YOUR_TOKEN_HERE

Tham số (body)

Tên	Kiểu	Bắt buộc	Mô tả
category_id	Integer	Không	ID danh mục
images	Array	Có	Mảng URL hoặc files

Code Example

CURL Example (File Upload)

curl -X POST https://kkdemo.kkwebsite.com/api/v2/data-images \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -F "category_id=1" \
  -F "images[]=@image1.jpg" \
  -F "images[]=@image2.jpg"

CURL Example (URL Upload)

curl -X POST https://kkdemo.kkwebsite.com/api/v2/data-images \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "category_id": 1,
    "images": [
        "https://example.com/image1.jpg",
        "https://example.com/image2.jpg"
    ]
  }'

N8N Example

Cấu hình HTTP Request Node:

• URL: https://kkdemo.kkwebsite.com/api/v2/data-images
• Method: POST
• Send Body: true
• Body Type: JSON
• Headers:

  Authorization: Bearer YOUR_TOKEN_HERE
  Content-Type: application/json

• Body (JSON):

  {
    "category_id": 1,
    "images": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg"
    ]
  }

PHP Example

function uploadImages($data, $token) {
    $url = 'https://kkdemo.kkwebsite.com/api/v2/data-images';
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Sử dụng
$data = [
    'category_id' => 1,
    'images' => [
        'https://example.com/image1.jpg',
        'https://example.com/image2.jpg'
    ]
];
$result = uploadImages($data, 'YOUR_TOKEN_HERE');

Python Example

import requests
import json

def upload_images(data, token):
    url = 'https://kkdemo.kkwebsite.com/api/v2/data-images'
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    response = requests.post(url, headers=headers, data=json.dumps(data))
    return response.json()

# Sử dụng
data = {
    'category_id': 1,
    'images': [
        'https://example.com/image1.jpg',
        'https://example.com/image2.jpg'
    ]
}
result = upload_images(data, 'YOUR_TOKEN_HERE')

Response

Success Response

{
    "status": "success",
    "message": "Đã tải lên 2 file thành công",
    "data": {
        "uploaded": [
            {
                "id": 1,
                "name": "abc123.jpg",
                "original_name": "image1.jpg",
                "url": "https://kkdemo.kkwebsite.com/image/images/20240101/abc123.jpg",
                "size": 1024000,
                "type": "image/jpeg",
                "category_id": 1
            }
        ],
        "errors": []
    }
}

Error Response

{
    "code": "UPLOAD_FAILED",
    "message": "Tải lên hình ảnh thất bại"
}

4. Cập Nhật Hình Ảnh

Mô tả

Cập nhật thông tin của hình ảnh.

Endpoint, Method, Authentication

PUT https://kkdemo.kkwebsite.com/api/v2/data-images/{id}

Authentication: Bearer token

Authorization: Bearer YOUR_TOKEN_HERE

Tham số (path)

Tên	Kiểu	Bắt buộc	Mô tả
id	Integer	Có	ID của hình ảnh

Tham số (body)

Tên	Kiểu	Bắt buộc	Mô tả
category_id	Integer	Không	ID danh mục mới
approve	Integer	Không	Trạng thái approve (0/1)
original_name	String	Không	Tên gốc của file

Code Example

CURL Example

curl -X PUT https://kkdemo.kkwebsite.com/api/v2/data-images/1 \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "category_id": 2,
    "approve": 1,
    "original_name": "new_name.jpg"
  }'

N8N Example

Cấu hình HTTP Request Node:

• URL: https://kkdemo.kkwebsite.com/api/v2/data-images/1
• Method: PUT
• Send Body: true
• Body Type: JSON
• Headers:

  Authorization: Bearer YOUR_TOKEN_HERE
  Content-Type: application/json

• Body (JSON):

  {
    "category_id": 2,
    "approve": 1,
    "original_name": "new_name.jpg"
  }

PHP Example

function updateImage($id, $data, $token) {
    $url = "https://kkdemo.kkwebsite.com/api/v2/data-images/{$id}";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token,
        'Content-Type: application/json'
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Sử dụng
$data = [
    'category_id' => 2,
    'approve' => 1,
    'original_name' => 'new_name.jpg'
];
$result = updateImage(1, $data, 'YOUR_TOKEN_HERE');

Python Example

import requests
import json

def update_image(image_id, data, token):
    url = f'https://kkdemo.kkwebsite.com/api/v2/data-images/{image_id}'
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }
    response = requests.put(url, headers=headers, data=json.dumps(data))
    return response.json()

# Sử dụng
data = {
    'category_id': 2,
    'approve': 1,
    'original_name': 'new_name.jpg'
}
result = update_image(1, data, 'YOUR_TOKEN_HERE')

Response

Success Response

{
    "status": "success",
    "message": "Cập nhật hình ảnh thành công",
    "data": {
        "id": 1,
        "updated_fields": ["category_id", "approve", "original_name"]
    }
}

Error Response

{
    "code": "VALIDATION_ERROR",
    "message": {
        "approve": "Approve chỉ chấp nhận 0 hoặc 1"
    }
}

5. Xóa Hình Ảnh

Mô tả

Xóa hình ảnh khỏi hệ thống.

Endpoint, Method, Authentication

DELETE https://kkdemo.kkwebsite.com/api/v2/data-images/{id}

Authentication: Bearer token

Authorization: Bearer YOUR_TOKEN_HERE

Tham số (path)

Tên	Kiểu	Bắt buộc	Mô tả
id	Integer	Có	ID của hình ảnh

Code Example

CURL Example

curl -X DELETE https://kkdemo.kkwebsite.com/api/v2/data-images/1 \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

N8N Example

Cấu hình HTTP Request Node:

• URL: https://kkdemo.kkwebsite.com/api/v2/data-images/1
• Method: DELETE
• Headers:

  Authorization: Bearer YOUR_TOKEN_HERE

PHP Example

function deleteImage($id, $token) {
    $url = "https://kkdemo.kkwebsite.com/api/v2/data-images/{$id}";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'DELETE');
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Sử dụng
$result = deleteImage(1, 'YOUR_TOKEN_HERE');

Python Example

import requests

def delete_image(image_id, token):
    url = f'https://kkdemo.kkwebsite.com/api/v2/data-images/{image_id}'
    headers = {'Authorization': f'Bearer {token}'}
    response = requests.delete(url, headers=headers)
    return response.json()

# Sử dụng
result = delete_image(1, 'YOUR_TOKEN_HERE')

Response

Success Response

{
    "status": "success",
    "message": "Xóa hình ảnh thành công",
    "data": {
        "id": 1
    }
}

Error Response

{
    "code": "NOT_FOUND",
    "message": "Không tìm thấy hình ảnh"
}

6. Lấy Hình Ảnh Ngẫu Nhiên

Mô tả

Lấy một hình ảnh ngẫu nhiên từ hệ thống.

Endpoint, Method, Authentication

GET https://kkdemo.kkwebsite.com/api/v2/data-images/random

Authentication: Bearer token

Authorization: Bearer YOUR_TOKEN_HERE

Tham số (query)

Tên	Kiểu	Bắt buộc	Mô tả
category_id	Integer	Không	Lọc theo category ID
approve	Integer	Không	Lọc theo trạng thái approve (0/1)

Code Example

CURL Example

curl -X GET "https://kkdemo.kkwebsite.com/api/v2/data-images/random?category_id=1&approve=1" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

N8N Example

Cấu hình HTTP Request Node:

• URL: https://kkdemo.kkwebsite.com/api/v2/data-images/random
• Method: GET
• Headers:

  Authorization: Bearer YOUR_TOKEN_HERE

• Query Parameters:

  category_id: 1
  approve: 1

PHP Example

function getRandomImage($token, $categoryId = null, $approve = null) {
    $url = 'https://kkdemo.kkwebsite.com/api/v2/data-images/random';
    $params = [];
    
    if ($categoryId !== null) $params['category_id'] = $categoryId;
    if ($approve !== null) $params['approve'] = $approve;
    
    if (!empty($params)) {
        $url .= '?' . http_build_query($params);
    }
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Sử dụng
$result = getRandomImage('YOUR_TOKEN_HERE', 1, 1);

Python Example

import requests

def get_random_image(token, category_id=None, approve=None):
    url = 'https://kkdemo.kkwebsite.com/api/v2/data-images/random'
    headers = {'Authorization': f'Bearer {token}'}
    params = {}
    
    if category_id is not None:
        params['category_id'] = category_id
    if approve is not None:
        params['approve'] = approve
    
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Sử dụng
result = get_random_image('YOUR_TOKEN_HERE', category_id=1, approve=1)

Response

Success Response

{
    "status": "success",
    "data": {
        "id": 1,
        "file_name": "abc123.jpg",
        "category_id": 1,
        "original_name": "image.jpg",
        "file_size": 1024000,
        "file_type": "image/jpeg",
        "width": 1920,
        "height": 1080,
        "approve": 1,
        "used": 6,
        "created_at": "2024-01-01 10:00:00",
        "updated_at": "2024-01-01 10:00:00",
        "url": "https://kkdemo.kkwebsite.com/image/images/20240101/abc123.jpg"
    }
}

Error Response

{
    "code": "NO_IMAGES_FOUND",
    "message": "Không tìm thấy hình ảnh phù hợp"
}

7. Tìm Kiếm Hình Ảnh

Mô tả

Tìm kiếm hình ảnh theo tên file với các bộ lọc.

Endpoint, Method, Authentication

GET https://kkdemo.kkwebsite.com/api/v2/data-images/search

Authentication: Bearer token

Authorization: Bearer YOUR_TOKEN_HERE

Tham số (query)

Tên	Kiểu	Bắt buộc	Mô tả
name	String	Không	Tìm kiếm chính xác theo tên file
search	String	Không	Tìm kiếm một phần theo tên file
category_id	Integer	Không	Lọc theo category ID
page	Integer	Không	Số trang (mặc định: 1)
limit	Integer	Không	Số lượng mỗi trang (mặc định: 20)

Code Example

CURL Example

curl -X GET "https://kkdemo.kkwebsite.com/api/v2/data-images/search?search=logo&category_id=1" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

N8N Example

Cấu hình HTTP Request Node:

• URL: https://kkdemo.kkwebsite.com/api/v2/data-images/search
• Method: GET
• Headers:

  Authorization: Bearer YOUR_TOKEN_HERE

• Query Parameters:

  search: logo
  category_id: 1

PHP Example

function searchImages($token, $search = null, $name = null, $categoryId = null, $page = 1, $limit = 20) {
    $url = 'https://kkdemo.kkwebsite.com/api/v2/data-images/search';
    $params = [
        'page' => $page,
        'limit' => $limit
    ];
    
    if ($search !== null) $params['search'] = $search;
    if ($name !== null) $params['name'] = $name;
    if ($categoryId !== null) $params['category_id'] = $categoryId;
    
    $url .= '?' . http_build_query($params);
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $token
    ]);
    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Sử dụng
$result = searchImages('YOUR_TOKEN_HERE', 'logo', null, 1);

Python Example

import requests

def search_images(token, search=None, name=None, category_id=None, page=1, limit=20):
    url = 'https://kkdemo.kkwebsite.com/api/v2/data-images/search'
    headers = {'Authorization': f'Bearer {token}'}
    params = {'page': page, 'limit': limit}
    
    if search is not None:
        params['search'] = search
    if name is not None:
        params['name'] = name
    if category_id is not None:
        params['category_id'] = category_id
    
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# Sử dụng
result = search_images('YOUR_TOKEN_HERE', search='logo', category_id=1)

Response

Success Response

{
    "status": "success",
    "data": [
        {
            "id": 1,
            "file_name": "abc123.jpg",
            "category_id": 1,
            "original_name": "image.jpg",
            "file_size": 1024000,
            "file_type": "image/jpeg",
            "width": 1920,
            "height": 1080,
            "approve": 1,
            "used": 5,
            "created_at": "2024-01-01 10:00:00",
            "updated_at": "2024-01-01 10:00:00",
            "url": "https://kkdemo.kkwebsite.com/image/images/20240101/abc123.jpg"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 20,
        "total": 5,
        "total_pages": 1
    },
    "message": "Tìm thấy 5 hình ảnh"
}

Error Response

{
    "code": "NO_RESULTS",
    "message": "Không tìm thấy kết quả phù hợp"
}

Error Codes

Các mã lỗi thường gặp

Code	Mô tả
UNAUTHORIZED	Token không hợp lệ hoặc hết hạn
NOT_FOUND	Không tìm thấy hình ảnh
VALIDATION_ERROR	Lỗi validation dữ liệu đầu vào
UPLOAD_FAILED	Tải lên hình ảnh thất bại
SYSTEM_ERROR	Lỗi hệ thống
NO_IMAGES_FOUND	Không tìm thấy hình ảnh phù hợp
NO_RESULTS	Không tìm thấy kết quả

Validation Rules

Upload Data

• category_id: Phải là số (optional)
• images: Mảng URL hoặc files (required)
• File upload: Tối đa 10MB, định dạng JPG, PNG, GIF
• URL: Phải là URL hợp lệ, tối đa 10MB

Update Data

• category_id: Phải là số (optional)
• approve: Chỉ chấp nhận 0 hoặc 1 (optional)
• original_name: Tối đa 255 ký tự (optional)

Rate Limits

• 1000 requests per hour cho mỗi token
• Upload limit: Tối đa 10 files mỗi request
• File size: Tối đa 10MB mỗi file