Интеграция функции конвертации изображений в промпты в ваше приложение открывает мощные возможности: автоматическая генерация описаний, инструменты визуального поиска, конвейеры создания контента и рекомендательные системы на основе визуального стиля. В этом техническом руководстве вы найдёте всё необходимое для интеграции ImageToPrompt API в ваш проект.

Примечание: ImageToPrompt API работает на базе Claude AI от Anthropic и обрабатывает изображения временно. Изображения никогда не сохраняются на сервере.

Обзор API

ImageToPrompt API предоставляет четыре основных эндпоинта, покрывающих все сценарии конвертации изображений/текста в AI-промпты. Каждый эндпоинт принимает POST-запрос с JSON-телом и возвращает структурированный ответ с сгенерированным промптом и полезными метаданными.

API размещён на серверлесс-функциях Vercel, что обеспечивает низкую задержку и высокую доступность. Среднее время ответа составляет 5-10 секунд в зависимости от сложности изображения и выбранной целевой модели.

Аутентификация и безопасность

Запросы к API требуют заголовка аутентификации с секретным ключом. Ключ передаётся в заголовке x-app-secret каждого запроса.

POST /api/analyze Content-Type: application/json x-app-secret: YOUR_APP_SECRET { "image": "data:image/jpeg;base64,/9j/4AAQ...", "model": "midjourney", "style": "cinematic" }

Все коммуникации шифруются по HTTPS. Изображения передаются в base64 в теле запроса и не проходят через небезопасные сторонние сервисы.

Доступные эндпоинты

Эндпоинт Метод Описание
/api/analyze POST Конвертация изображения в AI-промпт для целевой модели
/api/text-to-prompt POST Преобразование текстового описания в оптимизированный AI-промпт
/api/image-to-video-prompt POST Генерация AI-видеопромпта из исходного изображения
/api/text-to-video-prompt POST Создание AI-видеопромпта из текстового описания

Пример интеграции на Python

Ниже представлен полный пример интеграции на Python с использованием библиотеки requests. Этот скрипт кодирует локальное изображение в base64, отправляет запрос к API и выводит сгенерированный промпт.

import requests import base64 import json def image_to_prompt(image_path, model="midjourney", style="cinematic"): """Convert a local image to an AI prompt.""" # Read and encode the image with open(image_path, "rb") as f: image_data = base64.b64encode(f.read()).decode("utf-8") # Determine MIME type ext = image_path.lower().split(".")[-1] mime_types = {"jpg": "jpeg", "jpeg": "jpeg", "png": "png", "webp": "webp"} mime = mime_types.get(ext, "jpeg") # Build the request payload = { "image": f"data:image/{mime};base64,{image_data}", "model": model, "style": style } headers = { "Content-Type": "application/json", "x-app-secret": "YOUR_APP_SECRET" } response = requests.post( "https://www.imagetoprompt.dev/api/analyze", json=payload, headers=headers, timeout=30 ) if response.status_code == 200: result = response.json() return result elif response.status_code == 429: print("Rate limit reached. Try again tomorrow.") return None else: print(f"Error {response.status_code}: {response.text}") return None # Usage result = image_to_prompt("my-photo.jpg", model="flux", style="technical") if result: print("Prompt:", result["prompt"]) print("Negative:", result.get("negative", "N/A"))

Пример интеграции на JavaScript

Пример с использованием fetch для веб-приложений и Node.js. Этот код работает как на стороне браузера, так и на серверной стороне в Node.js 18+.

async function imageToPrompt(imageFile, model = "midjourney", style = "cinematic") { // Convert File to base64 const reader = new FileReader(); const base64 = await new Promise((resolve) => { reader.onload = () => resolve(reader.result); reader.readAsDataURL(imageFile); }); const response = await fetch("https://www.imagetoprompt.dev/api/analyze", { method: "POST", headers: { "Content-Type": "application/json", "x-app-secret": "YOUR_APP_SECRET" }, body: JSON.stringify({ image: base64, model: model, style: style }) }); if (response.status === 429) { throw new Error("Rate limit exceeded"); } if (!response.ok) { throw new Error(`API error: ${response.status}`); } return await response.json(); } // Usage with file input const fileInput = document.querySelector('input[type="file"]'); fileInput.addEventListener("change", async (e) => { const file = e.target.files[0]; try { const result = await imageToPrompt(file, "stable-diffusion", "technical"); console.log("Generated prompt:", result.prompt); } catch (err) { console.error("Failed:", err.message); } });

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

Каждый эндпоинт принимает определённые параметры, влияющие на генерацию промпта. Ниже приведены параметры основного эндпоинта /api/analyze.

Параметр Тип Обязательный Описание
image string Да Изображение в base64 с data URI-префиксом
model string Да Целевая модель: midjourney, stable-diffusion, flux, dall-e-3, adobe-firefly, leonardo-ai, ideogram
style string Нет Стиль промпта: cinematic, technical, artistic, minimal, epic, photographic

Формат ответа

API возвращает структурированный JSON-объект с основным промптом, негативным промптом (при наличии), креативными вариациями и метаданными визуального анализа.

{ "prompt": "cinematic portrait of a woman in golden hour light, shallow depth of field, film grain, warm tones --ar 3:2 --v 6.1 --style raw", "negative": "blurry, low quality, deformed, bad anatomy", "remix": "ethereal portrait bathed in amber sunset glow, dreamlike bokeh...", "colors": ["#D4A574", "#2C1810", "#F5E6D3", "#8B4513", "#FFD700"], "tags": ["portrait", "golden hour", "cinematic", "warm tones"], "aspectRatio": "3:2", "model": "midjourney", "style": "cinematic" }

Лимиты запросов и квоты

API использует систему ограничения запросов на основе IP-адресов через Upstash Redis. Текущие лимиты:

При превышении квоты API возвращает HTTP-код 429 с пояснительным сообщением. Реализуйте механизм повторных попыток с экспоненциальным откатом в клиентском коде.

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

API использует стандартные HTTP-коды для сообщений об ошибках. Вот наиболее распространённые коды и их значения:

Код Значение Рекомендуемое действие
200 Успех Обработайте ответ в обычном режиме
400 Невалидный запрос Проверьте формат изображения и параметры
401 Не аутентифицирован Проверьте ключ x-app-secret
429 Превышен лимит запросов Дождитесь сброса квоты или перейдите на платный план
500 Ошибка сервера Повторите попытку через несколько секунд с экспоненциальным откатом

Продвинутые сценарии использования

Конвейер генерации контента

Интегрируйте API в конвейер создания контента для автоматической генерации визуальных описаний из фотографий товаров, изображений портфолио или скриншотов дизайна. Это позволяет создавать стилистически согласованные вариации в масштабе.

Визуальный поисковый движок

Используйте сгенерированные промпты как семантические дескрипторы для индексации и поиска изображений по визуальному стилю. Теги цвета, стиля и атмосферы, возвращаемые API, формируют богатый индекс для поиска по визуальному сходству.

Образовательный инструмент для креативщиков

Создайте образовательный инструмент, разбирающий изображение на визуальные элементы (освещение, композиция, палитра, стиль), помогая художникам и фотографам понять, что делает изображение эффективным.

Автоматизация для социальных сетей

Автоматически генерируйте описательные подписи и хэштеги из визуалов. Сгенерированные промпты содержат наиболее релевантные термины для детального и привлекательного описания визуального контента.

Попробуйте API прямо сейчас

Начните с бесплатной квоты в 10 запросов в день. Для тестирования онлайн-инструмента регистрация не требуется.

Попробовать ImageToPrompt бесплатно →

Часто задаваемые вопросы

Бесплатен ли ImageToPrompt API?

API предоставляет бесплатную квоту в 10 запросов в день на IP-адрес. Эта квота разделяется между всеми эндпоинтами (image-to-prompt, text-to-prompt, image-to-video, text-to-video). Если вам нужно больше запросов, ознакомьтесь с платными планами на странице цен.

Какие форматы изображений поддерживает API?

API принимает изображения в форматах JPEG, PNG, WebP и GIF (только первый кадр). Максимальный размер — 10 МБ на изображение. Изображения передаются в base64-кодировке в теле JSON-запроса. Для лучших результатов используйте изображения размером не менее 512x512 пикселей.

Как обрабатывать ошибки и лимиты запросов API?

При достижении лимита API возвращает HTTP-код 429 с заголовком Retry-After, указывающим время повторной попытки. Реализуйте экспоненциальный откат в вашем коде. Код 400 указывает на проблему с запросом (невалидное изображение, отсутствующие параметры), а код 500 — на временную проблему сервера.

Сохраняются ли изображения, отправленные через API?

Нет. Все изображения обрабатываются временно в памяти и никогда не сохраняются на сервере. Анализ выполняется Claude AI в реальном времени, и данные удаляются сразу после генерации промпта. Логи изображений не ведутся.