Integrar la conversión de imagen a prompt en tus aplicaciones abre posibilidades poderosas: generación automatizada de descripciones, herramientas de búsqueda visual, pipelines de creación de contenido y sistemas de recomendación basados en el estilo visual. En esta guía técnica, cubrimos todo lo que los desarrolladores necesitan para integrar la API ImageToPrompt en sus proyectos.
Nota: La API de ImageToPrompt está impulsada por Claude AI de Anthropic y procesa las imágenes de forma efímera. Ninguna imagen se almacena jamás en nuestros servidores.
Presentación de la API
La API de ImageToPrompt expone cuatro endpoints principales que cubren todos los casos de uso de conversión de imagen/texto a prompt IA. Cada endpoint acepta solicitudes POST con un cuerpo JSON y devuelve una respuesta estructurada que contiene el prompt generado junto con metadatos útiles.
La API está alojada en Vercel como funciones serverless, lo que garantiza baja latencia y alta disponibilidad. Los tiempos de respuesta medios son de 5 a 10 segundos según la complejidad de la imagen y el modelo objetivo elegido.
Autenticación y Seguridad
Las solicitudes a la API requieren un header de autenticación que contenga tu clave secreta. Esta clave se transmite en el header x-app-secret de cada solicitud.
POST /api/analyze
Content-Type: application/json
x-app-secret: YOUR_APP_SECRET
{
"image": "data:image/jpeg;base64,/9j/4AAQ...",
"model": "midjourney",
"style": "cinematic"
}Todas las comunicaciones están cifradas mediante HTTPS. Las imágenes se transmiten en base64 dentro del cuerpo de la solicitud y nunca transitan por servicios de terceros no seguros.
Endpoints Disponibles
| Endpoint | Método | Descripción |
|---|---|---|
/api/analyze |
POST | Convierte una imagen en un prompt IA para el modelo objetivo |
/api/text-to-prompt |
POST | Transforma una descripción textual en un prompt IA optimizado |
/api/image-to-video-prompt |
POST | Genera un prompt de video IA a partir de una imagen fuente |
/api/text-to-video-prompt |
POST | Crea un prompt de video IA a partir de una descripción textual |
Ejemplo de Integración Python
Aquí tienes un ejemplo completo de integración en Python usando la biblioteca requests. Este script codifica una imagen local en base64, envía la solicitud a la API y muestra el prompt generado.
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"))Ejemplo de Integración JavaScript
Para aplicaciones web y Node.js, aquí tienes un ejemplo usando fetch. Este código funciona tanto del lado del navegador como del servidor con 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);
}
});Parámetros de Solicitud
Cada endpoint acepta parámetros específicos que influyen en la generación del prompt. Estos son los parámetros para el endpoint principal /api/analyze:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
image |
string | Sí | Imagen en base64 con prefijo data URI |
model |
string | Sí | Modelo objetivo: midjourney, stable-diffusion, flux, dall-e-3, adobe-firefly, leonardo-ai, ideogram |
style |
string | No | Estilo de prompt: cinematic, technical, artistic, minimal, epic, photographic |
Formato de Respuesta
La API devuelve un objeto JSON estructurado que contiene el prompt principal, el prompt negativo (si aplica), una variante creativa y metadatos sobre el análisis visual.
{
"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"
}Límites de Tasa y Cuotas
La API utiliza un sistema de limitación de tasa basado en la dirección IP con Upstash Redis. Los límites actuales son:
- Cuota gratuita: 10 solicitudes por día por dirección IP
- Cuota compartida: Las 10 solicitudes se comparten entre todos los endpoints (analyze, text-to-prompt, image-to-video-prompt, text-to-video-prompt)
- Reinicio: El contador se reinicia a medianoche UTC cada día
- Header de respuesta:
X-RateLimit-Remainingindica el número de solicitudes restantes
En caso de exceder la cuota, la API devuelve un código HTTP 429 con un mensaje explicativo. Implementa un mecanismo de reintento con backoff exponencial en tu código cliente.
Gestión de Errores
La API utiliza los códigos HTTP estándar para señalar errores. Estos son los códigos más comunes y su significado:
| Código | Significado | Acción recomendada |
|---|---|---|
| 200 | Éxito | Procesa la respuesta normalmente |
| 400 | Solicitud inválida | Verifica el formato de la imagen y los parámetros |
| 401 | No autenticado | Verifica tu clave x-app-secret |
| 429 | Límite de tasa alcanzado | Espera el reinicio de la cuota o cambia al plan de pago |
| 500 | Error del servidor | Reintenta después de unos segundos con backoff exponencial |
Casos de Uso Avanzados
Pipeline de generación de contenido
Integra la API en tu pipeline de creación de contenido para generar automáticamente descripciones visuales a partir de fotos de productos, imágenes de portfolio o capturas de pantalla de diseño. Esto permite crear variaciones de estilo coherentes a gran escala.
Motor de búsqueda visual
Usa los prompts generados como descriptores semánticos para indexar y buscar imágenes por estilo visual. Las etiquetas de color, estilo y ambiente devueltas por la API crean un índice rico para la búsqueda por similitud visual.
Herramienta de formación creativa
Construye herramientas educativas que descompongan las imágenes en sus componentes visuales (iluminación, composición, paleta, estilo) para ayudar a artistas y fotógrafos a entender qué hace que una imagen sea efectiva.
Automatización de redes sociales
Genera automáticamente descripciones y hashtags a partir de tus contenidos visuales. El prompt generado contiene los términos más relevantes para describir el contenido visual de manera detallada y atractiva.
Prueba la API Ahora
Pruébala gratis con 10 solicitudes por día. No se requiere registro para probar la herramienta en línea.
Probar ImageToPrompt Gratis →Preguntas Frecuentes
¿La API de ImageToPrompt es gratuita?
La API ofrece una cuota gratuita de 10 solicitudes por día por dirección IP. Esta cuota se comparte entre todos los endpoints (image-to-prompt, text-to-prompt, image-to-video, text-to-video). Para volúmenes mayores, consulta nuestros planes de precios en la página Pricing.
¿Qué formatos de imagen soporta la API?
La API acepta imágenes en formato JPEG, PNG, WebP y GIF (solo el primer fotograma). El tamaño máximo es de 10 MB por imagen. Las imágenes se envían en base64 dentro del cuerpo de la solicitud JSON. Para mejores resultados, usa imágenes de al menos 512x512 píxeles.
¿Cómo gestionar los errores y los límites de tasa en la API?
La API devuelve un código HTTP 429 cuando se alcanza el límite de tasa, con un header Retry-After que indica cuándo reintentar. Implementa un backoff exponencial en tu código. Los errores 400 indican un problema con la solicitud (imagen inválida, parámetros faltantes) y los errores 500 señalan un problema temporal del servidor.
¿Las imágenes enviadas a la API se almacenan?
No. Todas las imágenes se procesan en memoria de forma efímera y nunca se almacenan en nuestros servidores. El análisis lo realiza Claude AI en tiempo real y los datos se eliminan inmediatamente después de generar el prompt. No se conserva ningún registro de imágenes.