Vision AI API для разработчиков: полный гайд по интеграции

Если вы разработчик и хотите встроить AI-генерацию интерьеров в ваш продукт — этот гайд для вас.

Vision AI предоставляет REST API, который позволяет:

• Генерировать интерьеры программно (из вашего приложения)
• Управлять проектами и файлами
• Получать результаты в нужном разрешении
• Встраивать в любой тек-стек

Начало работы с API

Что вам понадобится

• API ключ (получите в консоли разработчика)
• Базовое понимание REST API и JSON
• HTTP-клиент (curl, Postman, или библиотека вашего языка)
• Тестовые данные (фотографии помещений)

Где получить API ключ

1. 1Зарегистрируйтесь на vision-ai.org
2. 2Перейдите в Developer Console
3. 3Нажмите "Create API Key"
4. 4Скопируйте ключ (храните безопасно!)

Версия API

Текущая версия: v1 URL базы: `https://api.vision-ai.org/v1/`

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

Bearer Token

Все запросы требуют Authorization header:

```bash curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.vision-ai.org/v1/projects ```

Безопасность ключа

⚠️ Важно:

• Никогда не коммитьте API ключ в код
• Используйте переменные окружения (`.env`)
• Ротируйте ключи регулярно
• Используйте разные ключи для разных окружений (dev/staging/prod)

Основные endpoint'ы

1. Создание проекта

``` POST /projects ```

Параметры: ```json { "name": "Квартира на ул. Ленина", "description": "Дизайн гостиной" } ```

Ответ: ```json { "id": "proj_abc123", "name": "Квартира на ул. Ленина", "created_at": "2026-04-13T10:30:00Z", "status": "active" } ```

2. Загрузка изображения

``` POST /projects/{project_id}/images Content-Type: multipart/form-data ```

Параметры:

• `file`: бинарные данные изображения (JPG, PNG)
• `description` (опционально): описание комнаты

Ответ: ```json { "id": "img_xyz789", "project_id": "proj_abc123", "url": "https://cdn.vision-ai.org/img_xyz789.jpg", "status": "uploaded" } ```

3. Генерация визуализации

``` POST /projects/{project_id}/generate ```

Параметры: ```json { "image_id": "img_xyz789", "style": "modern", "variants": 3, "resolution": "high" } ```

Стили: modern, scandinavian, minimalist, classic, loft, art-deco, boho, japanese, industrial

Ответ: ```json { "generation_id": "gen_def456", "status": "processing", "estimated_time": 45 } ```

4. Получение результата

``` GET /generations/{generation_id} ```

Ответ: ```json { "id": "gen_def456", "status": "completed", "results": [ { "id": "result_1", "url": "https://cdn.vision-ai.org/result_1.jpg", "variant": 1, "style": "modern" }, { "id": "result_2", "url": "https://cdn.vision-ai.org/result_2.jpg", "variant": 2, "style": "modern" } ] } ```

Примеры кода

Python

```python import requests import os

API_KEY = os.getenv('VISION_AI_API_KEY') BASE_URL = 'https://api.vision-ai.org/v1'

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

# Создание проекта project_data = { 'name': 'Гостиная', 'description': 'Современный дизайн' }

response = requests.post( f'{BASE_URL}/projects', json=project_data, headers=headers )

project = response.json() project_id = project['id']

# Загрузка изображения with open('living_room.jpg', 'rb') as f: files = {'file': f} img_response = requests.post( f'{BASE_URL}/projects/{project_id}/images', files=files, headers=headers )

image = img_response.json() image_id = image['id']

# Генерация gen_data = { 'image_id': image_id, 'style': 'modern', 'variants': 3 }

gen_response = requests.post( f'{BASE_URL}/projects/{project_id}/generate', json=gen_data, headers=headers )

generation = gen_response.json() print(f"Генерация запущена: {generation['generation_id']}") ```

JavaScript/Node.js

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

const API_KEY = process.env.VISION_AI_API_KEY; const BASE_URL = 'https://api.vision-ai.org/v1';

const client = axios.create({ headers: { 'Authorization': `Bearer ${API_KEY}` } });

async function generateInterior() { try { // Создание проекта const projectRes = await client.post(`${BASE_URL}/projects`, { name: 'Гостиная', description: 'Современный дизайн' });

const projectId = projectRes.data.id;

// Загрузка изображения const form = new FormData(); form.append('file', fs.createReadStream('living_room.jpg'));

const imgRes = await client.post( `${BASE_URL}/projects/${projectId}/images`, form, { headers: form.getHeaders() } );

const imageId = imgRes.data.id;

// Генерация const genRes = await client.post( `${BASE_URL}/projects/${projectId}/generate`, { image_id: imageId, style: 'modern', variants: 3 } );

console.log(`Generation started: ${genRes.data.generation_id}`); } catch (error) { console.error('Error:', error.response?.data || error.message); } }

generateInterior(); ```

Webhooks и callbacks

Настройка webhook'а

Вместо polling'а используйте webhook'и для уведомлений о завершении.

``` POST /webhooks ```

Параметры: ```json { "url": "https://yourapp.com/webhooks/vision-ai", "events": ["generation.completed", "generation.failed"], "secret": "your-webhook-secret" } ```

Обработка webhook события

```python from flask import Flask, request import hmac import hashlib

app = Flask(__name__)

WEBHOOK_SECRET = 'your-webhook-secret'

@app.route('/webhooks/vision-ai', methods=['POST']) def handle_webhook(): # Проверка подписи signature = request.headers.get('X-Vision-Signature') payload = request.get_data()

expected_sig = hmac.new( WEBHOOK_SECRET.encode(), payload, hashlib.sha256 ).hexdigest()

if signature != expected_sig: return 'Invalid signature', 403

data = request.json

if data['event'] == 'generation.completed': # Обработка завершённой генерации print(f"Generation {data['generation_id']} completed!") print(f"Results: {data['results']}")

return 'OK', 200 ```

Лучшие практики

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

```python try: response = requests.post(url, json=data, headers=headers) response.raise_for_status() # Вызовет исключение при 4xx/5xx except requests.exceptions.HTTPError as e: # Обработка ошибок API error_data = e.response.json() print(f"API Error: {error_data['error']['message']}") except requests.exceptions.RequestException as e: # Обработка других сетевых ошибок print(f"Network error: {e}") ```

2. Retry логика

```python from tenacity import retry, wait_exponential, stop_after_attempt

@retry( wait=wait_exponential(multiplier=1, min=2, max=10), stop=stop_after_attempt(3) ) def call_api(url, kwargs): return requests.post(url, kwargs) ```

3. Rate limiting

Vision AI API имеет rate limits:

• 100 requests/minute для стандартного плана
• 1000 requests/minute для enterprise

Добавьте backoff:

```python from time import sleep

remaining = int(response.headers.get('X-RateLimit-Remaining', 100)) if remaining < 10: sleep(60) # Дождитесь сброса лимита ```