Describir una imagen
Una carpeta con diez mil fotos sin etiquetar es, antes que nada, un problema de búsqueda: no se puede encontrar lo que no se puede describir. La API para describir imagen analiza una foto y devuelve una oración simple que dice qué hay realmente en ella, dándole a cada imagen un texto buscable y ordenable asociado. Envía una imagen y recibe una descripción que puede indexar, filtrar o pasar a otro sistema.
Ejecútela online
Ejecute esto en nuestros servidores con su cuenta. Las herramientas gratuitas corren en su navegador; esta cobra de su saldo del KIT según el precio de arriba.
Una tarea distinta al texto alternativo
Vale la pena ser precisos sobre para qué sirve este endpoint: una descripción de imagen describe el contenido para búsqueda, catalogación, moderación o para alimentar otro sistema; no está escrita para cumplir con requisitos de accesibilidad, aunque a menudo coincide en el contenido. Mientras el texto alternativo se redacta para leerse en voz alta en lugar de la imagen, una descripción de este endpoint se redacta para ser indexada, buscada, filtrada y comparada, lo que la orienta hacia descripciones consistentes y literales del sujeto y la escena.
Qué recibe de vuelta
Envía una imagen por POST a /image/caption y la tarea devuelve una oración en lenguaje sencillo que identifica el sujeto principal y el entorno: un perro corriendo en una playa, una factura impresa sobre un escritorio de madera, tres personas en una mesa de reuniones. La descripción se genera directamente del contenido de la imagen, no del nombre del archivo ni de ningún metadato adjunto, algo que importa muchísimo para cualquier foto que llegó con un nombre autogenerado y sin sentido desde una cámara o un teléfono.
El problema que resuelve en realidad
Las bibliotecas de fotos de stock, los sistemas de gestión de activos digitales y los archivos fotográficos internos comparten el mismo punto de falla: la búsqueda solo funciona si algo describió la imagen en texto, y describir manualmente decenas de miles de archivos nunca sucede. Este endpoint convierte una pila de JPEG imposible de buscar en un conjunto de datos que una búsqueda de texto normal puede consultar, que es la diferencia entre encontrar una foto en segundos y pasar una hora revisando carpetas.
Cómo se conecta con un sistema más grande
Como la descripción corre de forma asíncrona, suele ser la primera etapa de un flujo más grande en vez de un paso aislado: la descripción alimenta un índice de búsqueda, se analiza contra reglas de moderación en busca de términos marcados, o se guarda como campo de metadato junto al archivo. Se envía un lote de imágenes, los resultados llegan por webhook conforme cada una termina, y los sistemas posteriores recogen las descripciones a medida que llegan en vez de esperar a que termine todo el lote.
Un precio a escala del uso real
El endpoint cobra una tarifa fija pequeña por solicitud más un monto por imagen, así que describir una sola foto o procesar un archivo entero cuestan en proporción directa al trabajo realizado. Los intentos fallidos reintentan automáticamente hasta tres veces y nunca se cobran, así que procesar un archivo grande solo genera costo por las descripciones que realmente se produjeron.
Qué puede hacer con ella
Búsqueda en una biblioteca de activos digitales
Una empresa de medios describe un archivo de fotos sin etiquetar para que su herramienta de búsqueda interna devuelva imágenes relevantes por tema en vez de depender de nombres de archivo crípticos.
Preselección para moderación de contenido
Una plataforma describe las imágenes subidas por usuarios como primer filtro, alimentando el texto de la descripción a reglas automatizadas antes de que la imagen pase a revisión adicional.
Etiquetado de un catálogo de fotos de stock
Un sitio de fotografía de stock genera descripciones para las imágenes recién ingresadas y así completa automáticamente palabras clave y descripciones buscables para los compradores.
Análisis de imágenes para monitoreo de marca
Una herramienta de monitoreo de marca describe las imágenes compartidas en publicaciones para entender el contenido visual junto con las menciones de texto, sin revisar cada foto manualmente.
Preguntas frecuentes
¿Cuál es la diferencia entre la API para describir imagen y la generación de texto alternativo?
Describir imagen produce una descripción literal del contenido para búsqueda, catalogación o moderación, mientras que el texto alternativo está formateado específicamente para uso de accesibilidad dentro de un atributo alt; el contenido puede coincidir pero la intención es distinta.
¿Cómo es una descripción típica?
Una oración corta en lenguaje sencillo que nombra el sujeto principal y el entorno, como 'un perro corriendo en una playa', generada a partir del contenido real de la imagen, no del nombre del archivo ni de sus metadatos.
¿Puedo describir un archivo grande de imágenes en lote?
Sí, cada imagen es una solicitud y la tarea es asíncrona, así que un script puede enviar un archivo completo y recolectar las descripciones por webhook conforme cada una se completa.
¿Qué formatos de imagen acepta la API para describir imagen?
Se aceptan imágenes en JPEG, PNG y WebP como entrada.
¿La API para describir imagen es gratuita?
No hay capa gratuita: las capas gratis se abusan y ralentizan a todos. El acceso funciona con un saldo prepago de ForHosting KIT: se recarga desde $10.00 (no caduca) y cada solicitud se cobra a su precio publicado, así que una llamada sin saldo devuelve HTTP 402. Sin suscripción, sin tokens ni créditos inventados, y una tarea fallida no se cobra.
¿Cómo recibo la descripción, por sondeo o por webhook?
La tarea devuelve un task_id de inmediato y corre de forma asíncrona; la descripción llega por webhook firmado, o puede obtenerla desde un enlace firmado válido por 24 horas.
¿Puedo usar las descripciones para moderación de contenido?
Sí, muchos equipos alimentan el texto de la descripción devuelta a sus propias reglas de moderación o filtros de palabras clave como primer paso antes de una revisión más profunda.
¿Qué pasa si falla la generación de una descripción?
La tarea reintenta automáticamente hasta tres veces antes de devolver un error claro, y una solicitud fallida nunca se cobra.
Para desarrolladores — acceso por API
Todo lo de esta página está disponible por programación. Esta sección es para equipos que quieren integrarlo en sus sistemas; el resto puede usar la herramienta de arriba sin más.
Endpoint de API
¿Prefiere automatizarlo? Un POST autenticado crea la tarea; el resultado llega por webhook o enlace firmado. La misma capacidad también se ejecuta aquí en la web, y pronto desde nuestra app, el email y Telegram.
Llámela desde su stack
curl -X POST https://api.kit.forhosting.com/image/caption \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"image":"https://ejemplo.com/imagen.jpg"}'const res = await fetch("https://api.kit.forhosting.com/image/caption", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"image": "https://ejemplo.com/imagen.jpg"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/image/caption",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"image": "https://ejemplo.com/imagen.jpg"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/image/caption", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"image":"https://ejemplo.com/imagen.jpg"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"image":"https://ejemplo.com/imagen.jpg"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/image/caption", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Ejemplo de solicitud
{
"image": "https://ejemplo.com/imagen.jpg"
}Ejemplo de respuesta
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "image.caption",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}La API es asíncrona: la llamada devuelve un task_id al instante y el resultado llega por webhook. El polling está limitado a 1 req/s por tarea.
Precio
Precio publicado — sin tokens ni créditos inventados. Una tarea fallida no se cobra.
Límites
max_mb | 15 |
max_megapixels | 12 |
Errores
| HTTP | Código | Significado |
|---|---|---|
401 | unauthorized | API key ausente o inválida. |
402 | insufficient_balance | El saldo no cubre el precio de la tarea. |
404 | unknown_type | El tipo de tarea no existe. |
429 | rate_limited | Demasiadas peticiones. Use el webhook en vez de sondear. |
422 | task_failed | La tarea falló tras 3 reintentos. No se cobra. |