API Документация

Аутентификация

Все запросы к API должны содержать API-ключ. Поддерживается два способа передачи:

Способ 1: Заголовок Authorization (рекомендуется)

Authorization: Bearer YOUR_API_KEY

Способ 2: Заголовок X-API-Key

X-API-Key: YOUR_API_KEY

Обработка ошибок

API возвращает ошибки в стандартном формате:

{
    "success": false,
    "error": {
        "code": 400,
        "message": "Описание ошибки"
    }
}

Коды ошибок

POST /analyze

Загрузить и проанализировать изображение.

Параметры запроса

* Один из параметров image, image_base64 или image_url обязателен

Пример запроса (файл)

curl -X POST https://vision.bakatuev.ru/api/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@photo.jpg" \
  -F "model=google/gemma-3-27b"

Пример запроса (Base64)

curl -X POST https://vision.bakatuev.ru/api/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "image_base64=data:image/jpeg;base64,/9j/4AAQ..." \
  -d "prompt=Опиши что изображено на фото"

Пример запроса (URL)

curl -X POST https://vision.bakatuev.ru/api/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "image_url=https://example.com/photo.jpg"

Успешный ответ

{
    "success": true,
    "data": {
        "image": {
            "id": 123,
            "filename": "20241209_143022_a1b2c3d4.jpg",
            "original_name": "photo.jpg",
            "url": "/assets/uploads/20241209_143022_a1b2c3d4.jpg",
            "file_size": 245760,
            "mime_type": "image/jpeg",
            "status": "completed",
            "description": "На изображении показан...",
            "model_used": "google/gemma-3-27b",
            "tokens_used": 512,
            "processing_time": 2.345,
            "created_at": "2024-12-09 14:30:22"
        },
        "remaining_requests": 95
    }
}

GET /images

Получить список изображений пользователя.

Query параметры

Пример запроса

curl -X GET "https://vision.bakatuev.ru/api/v1/images?page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Ответ

{
    "success": true,
    "data": {
        "images": [
            {
                "id": 123,
                "filename": "20241209_143022_a1b2c3d4.jpg",
                "original_name": "photo.jpg",
                "status": "completed",
                "description": "На изображении...",
                "created_at": "2024-12-09 14:30:22"
            }
        ],
        "pagination": {
            "page": 1,
            "per_page": 10,
            "total": 45,
            "total_pages": 5
        }
    }
}

GET /images/{id}

Получить информацию о конкретном изображении.

Пример запроса

curl -X GET https://vision.bakatuev.ru/api/v1/images/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Ответ

{
    "success": true,
    "data": {
        "image": {
            "id": 123,
            "filename": "20241209_143022_a1b2c3d4.jpg",
            "original_name": "photo.jpg",
            "url": "/assets/uploads/20241209_143022_a1b2c3d4.jpg",
            "file_size": 245760,
            "mime_type": "image/jpeg",
            "status": "completed",
            "description": "На изображении показан...",
            "model_used": "google/gemma-3-27b",
            "tokens_used": 512,
            "processing_time": 2.345,
            "error_message": null,
            "created_at": "2024-12-09 14:30:22"
        }
    }
}

DELETE /images/{id}

Удалить изображение.

Пример запроса

curl -X DELETE https://vision.bakatuev.ru/api/v1/images/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Ответ

{
    "success": true,
    "data": {
        "message": "Изображение удалено"
    }
}

POST /images/{id}/reanalyze

Повторно проанализировать существующее изображение (с другой моделью или промптом).

Параметры

Пример запроса

curl -X POST https://vision.bakatuev.ru/api/v1/images/123/reanalyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "prompt=Подробно опиши все объекты на изображении"

GET /stats

Получить статистику использования.

Пример запроса

curl -X GET https://vision.bakatuev.ru/api/v1/stats \
  -H "Authorization: Bearer YOUR_API_KEY"

Ответ

{
    "success": true,
    "data": {
        "user": {
            "id": 1,
            "username": "user123"
        },
        "usage": {
            "total_images": 156,
            "today_images": 12,
            "requests_limit": 100,
            "requests_used": 45,
            "requests_remaining": 55
        },
        "api_key": {
            "name": "Production Key",
            "requests_count": 1234,
            "expires_at": "2025-12-31"
        }
    }
}

GET /models

Получить список доступных моделей.

Пример запроса

curl -X GET https://vision.bakatuev.ru/api/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Ответ

{
    "success": true,
    "data": {
        "models": [
            "google/gemma-3-27b",
            "llava-v1.6"
        ],
        "default": "google/gemma-3-27b"
    }
}

Примеры кода

Python

import requests

API_KEY = "your_api_key"
BASE_URL = "https://vision.bakatuev.ru/api/v1"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Анализ изображения из файла
with open("photo.jpg", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/analyze",
        headers=headers,
        files={"image": f},
        data={"prompt": "Опиши изображение"}
    )
    print(response.json())

# Анализ по URL
response = requests.post(
    f"{BASE_URL}/analyze",
    headers=headers,
    data={
        "image_url": "https://example.com/photo.jpg",
        "model": "google/gemma-3-27b"
    }
)
print(response.json())

JavaScript (Node.js)

const fs = require('fs');
const FormData = require('form-data');
const axios = require('axios');

const API_KEY = 'your_api_key';
const BASE_URL = 'https://vision.bakatuev.ru/api/v1';

const headers = { Authorization: `Bearer ${API_KEY}` };

// Анализ изображения из файла
async function analyzeFile() {
    const form = new FormData();
    form.append('image', fs.createReadStream('photo.jpg'));
    form.append('prompt', 'Опиши изображение');

    const response = await axios.post(`${BASE_URL}/analyze`, form, {
        headers: { ...headers, ...form.getHeaders() }
    });
    console.log(response.data);
}

// Получение статистики
async function getStats() {
    const response = await axios.get(`${BASE_URL}/stats`, { headers });
    console.log(response.data);
}

analyzeFile();

PHP

<?php
$apiKey = 'your_api_key';
$baseUrl = 'https://vision.bakatuev.ru/api/v1';

// Анализ изображения
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "$baseUrl/analyze",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $apiKey",
    ],
    CURLOPT_POSTFIELDS => [
        'image' => new CURLFile('photo.jpg'),
        'prompt' => 'Опиши изображение',
    ],
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
print_r($data);