Documentación de API

Optimización de Imágenes

SDK

Además de la API REST, el SDK oficial para TypeScript y JavaScript gestiona la autenticación, las solicitudes multipart y el filtrado de campos de las imágenes.

Instalación

Instala el SDK de optimización de imágenes desde npm. Puedes usar @ircg/ios para este servicio o @ircg/sdk para todos los servicios de IRCG.

typescript

	# Solo este servicio
	npm install @ircg/ios
	# O el meta-paquete
	npm install @ircg/sdk

Uso básico

Inicializa IOSClient con tu API key y sube una imagen. Los métodos seguros devuelven error en vez de lanzar una excepción.

typescript

	import { File } from 'node:buffer'
	import { readFile } from 'node:fs/promises'
	import { IOSClient } from '@ircg/ios'
	
	const apiKey = process.env.IRCG_API_KEY
	if (!apiKey) throw new Error('Configura IRCG_API_KEY en el servidor')
	const image = new File([await readFile('./product.jpg')], 'product.jpg', { type: 'image/jpeg' })
	const ios = new IOSClient({ apiKey, lang: 'es' })
	const result = await ios.upload({ image, requireSignedURLs: false, fields: ['imageId', 'currentVariants'] })
	if (result.error) throw new Error(result.error.message)
	console.log(ios.getImageUrl(result.optimizedImage.imageId, '500x500'))

Dry run

Configura dryRun: true para recibir respuestas sintéticas tipadas sin realizar solicitudes HTTP ni consumir créditos. Todas las operaciones remotas se simulan; las listas regresan vacías y no se conserva estado entre llamadas.

typescript

	const ios = new IOSClient({ apiKey: 'unused', dryRun: true })
	const result = await ios.upload({ image, fields: ['imageId', 'currentVariants'] })
	if (result.error) throw new Error(result.error.message)
	console.log(result.optimizedImage.imageId) // "dry-run-image"

API REST

Método	Ruta	Descripción
POST	/api/v1/images	Subir una imagen.
GET	/api/v1/images	Listar imágenes.
GET	/api/v1/images/:imageId	Consultar una imagen.
POST	/api/v1/images/:imageId/sign	Firmar una URL de imagen.
DELETE	/api/v1/images/:imageId	Eliminar una imagen.

Subir Imagen POST

typescript

	import { File } from 'node:buffer'
	import { readFile } from 'node:fs/promises'
	import { IOSClient } from '@ircg/ios'
	
	const ios = new IOSClient({ apiKey: API_KEY, lang: 'es' })
	const imageFile = new File([await readFile('./product.jpg')], 'product.jpg', { type: 'image/jpeg' })
	const result = await ios.upload({
		image: imageFile,
		requireSignedURLs: false,
		fields: ['imageId', 'name', 'requireSignedURLs', 'currentVariants'],
	})
	if (result.error) throw new Error(result.error.message)
	console.log(result.optimizedImage.imageId)
	
	const formData = new FormData()
	formData.append('image', imageFile)
	formData.append('requireSignedURLs', 'false')
	const response = await fetch('https://ircg.dev/api/v1/images?fields=%5B%22imageId%22%2C%22name%22%2C%22requireSignedURLs%22%2C%22currentVariants%22%5D', {
		method: 'POST',
		headers: { Authorization: `Bearer ${API_KEY}`, 'Accept-Language': 'es' },
		body: formData,
	})
	if (!response.ok) throw new Error(`Upload failed: ${response.status}`)
	const data = await response.json()
	console.log(data.optimizedImage.imageId)

Parámetros opcionales

https://ircg.dev/api/v1/images?fields=["imageId","name","requireSignedURLs","currentVariants"]

Parámetro	Tipo	Valores permitidos	Por defecto	Descripción
fields	string	Arreglo JSON de nombres de campos	Todos los campos	Especifica qué campos incluir en la respuesta. Campos disponibles: `imageId`, `name`, `requireSignedURLs`, `createdAt`, `requests`, `currentVariants`, `placeholderBase64`. `currentVariants` enumera los nombres, dimensiones y URLs disponibles. `placeholderBase64` contiene una imagen de baja resolución generada con la variante `placeholder` (`32x32`); puedes guardarla con los datos de la imagen y mostrarla mientras carga la imagen definitiva. Ejemplo: `?fields=["imageId","name","currentVariants"]`

Cuerpo

Campo	Tipo	Requerido	Por defecto	Descripción
image	File	Sí	-	El archivo de imagen a subir y optimizar.
requireSignedURLs	boolean	No	-	Si la imagen requiere URLs firmadas para acceso. Default: false

Respuestas

200

Respuesta satisfactoria

204

Respuesta satisfactoria (No content)

400

Error en body o parámetros de la petición

401

Error de autenticación

429

Demasiadas solicitudes

500

Error inesperado

Listar Imágenes GET

typescript

	import { IOSClient } from '@ircg/ios'
	
	const ios = new IOSClient({ apiKey: API_KEY, lang: 'es' })
	const result = await ios.getAll({
		page: 1,
		amount: 50,
		fields: ['imageId', 'name', 'requireSignedURLs', 'requests'],
	})
	if (result.error) throw new Error(result.error.message)
	console.log(result.optimizedImages, result.totalAmount)
	
	const response = await fetch('https://ircg.dev/api/v1/images?fields=%5B%22imageId%22%2C%22name%22%2C%22requireSignedURLs%22%2C%22requests%22%5D', {
		headers: { Authorization: `Bearer ${API_KEY}`, 'Accept-Language': 'es' },
	})
	if (!response.ok) throw new Error(`List failed: ${response.status}`)
	const data = await response.json()
	console.log(data.optimizedImages, data.totalAmount)

Parámetros opcionales

https://ircg.dev/api/v1/images?fields=["imageId","name","requests"]&amount=100&page=3&ascending=true

Parámetro	Tipo	Valores permitidos	Por defecto	Descripción
fields	string	Arreglo JSON de nombres de campos	Todos los campos	Campos disponibles: `imageId`, `name`, `requireSignedURLs`, `createdAt` y `requests`.
amount	number	1 - 100	50	Útil para la paginación.
page	number	1 - 99999	1	Útil para la paginación.
ascending	boolean	true false	false	Ordena la lista tomando en cuenta la fecha de creación (`createdAt`).

Respuestas

200

Respuesta satisfactoria

400

Error en body o parámetros de la petición

401

Error de autenticación

429

Demasiadas solicitudes

500

Error inesperado

Obtener Imagen por ID GET

typescript

	import { IOSClient } from '@ircg/ios'
	
	const ios = new IOSClient({ apiKey: API_KEY, lang: 'es' })
	const imageId = 'abc123'
	const result = await ios.getById({
		imageId,
		fields: ['imageId', 'name', 'requireSignedURLs', 'currentVariants'],
	})
	if (result.error) throw new Error(result.error.message)
	console.log(result.optimizedImage)
	
	const response = await fetch(`https://ircg.dev/api/v1/images/${imageId}?fields=%5B%22imageId%22%2C%22name%22%2C%22requireSignedURLs%22%2C%22currentVariants%22%5D`, {
		headers: { Authorization: `Bearer ${API_KEY}`, 'Accept-Language': 'es' },
	})
	if (!response.ok) throw new Error(`Read failed: ${response.status}`)
	const data = await response.json()
	console.log(data.optimizedImage)

Segmento de ruta

https://ircg.dev/api/v1/images/:imageId

Segmento	Tipo	Descripción
imageId	string	El identificador único de la imagen.

Parámetros opcionales

https://ircg.dev/api/v1/images/:imageId?fields=["imageId","name","currentVariants"]

Parámetro	Tipo	Valores permitidos	Por defecto	Descripción
fields	string	Arreglo JSON de nombres de campos	Todos los campos	Especifica qué campos incluir en la respuesta. Campos disponibles: `imageId`, `name`, `requireSignedURLs`, `createdAt`, `requests`, `currentVariants`, `placeholderBase64`. `currentVariants` enumera los nombres, dimensiones y URLs disponibles. `placeholderBase64` contiene una imagen de baja resolución generada con la variante `placeholder` (`32x32`); puedes guardarla con los datos de la imagen y mostrarla mientras carga la imagen definitiva. Ejemplo: `?fields=["imageId","name","requests","currentVariants"]`

Respuestas

200

Respuesta satisfactoria

400

Error en body o parámetros de la petición

401

Error de autenticación

404

No se encontró algún recurso

429

Demasiadas solicitudes

500

Error inesperado

Firmar Imagen POST

typescript

	import { IOSClient } from '@ircg/ios'
	
	const ios = new IOSClient({ apiKey: API_KEY, lang: 'es' })
	const imageId = 'abc123'
	const variant = '500x500' // También puedes usar el nombre de la variante.
	const result = await ios.signImage({
		imageId,
		variant,
		reuseSignature: true,
		fields: ['sig', 'exp', 'imageId', 'signedUrl', 'requests'],
	})
	if (result.error) throw new Error(result.error.message)
	console.log(result.optimizedImage.signedUrl)
	
	const response = await fetch(`https://ircg.dev/api/v1/images/${imageId}/sign?variant=${variant}&fields=%5B%22sig%22%2C%22exp%22%2C%22imageId%22%2C%22signedUrl%22%2C%22requests%22%5D&reuseSignature=true`, {
		method: 'POST',
		headers: { Authorization: `Bearer ${API_KEY}`, 'Accept-Language': 'es' },
	})
	if (!response.ok) throw new Error(`Signing failed: ${response.status}`)
	console.log((await response.json()).optimizedImage.signedUrl)

El parámetro variant acepta el nombre configurado, como product, o dimensiones en formato ancho×alto, como 500x500.

Segmento de ruta

https://ircg.dev/api/v1/images/:imageId/sign

Segmento	Tipo	Descripción
imageId	string	El identificador único de la imagen.

Parámetros opcionales

https://ircg.dev/api/v1/images/:imageId/sign?variant=original&fields=["sig","exp","signedUrl"]&reuseSignature=true

Cuando reuseSignature=true, el servidor puede reutilizar una URL firmada cacheada para el mismo imageId + variant. Las firmas cacheadas se guardan por ~58 minutos (la firma subyacente expira después de ~60 minutos).

Parámetro	Tipo	Valores permitidos	Por defecto	Descripción
variant	string	original, thumbnail, etc.	original	La variante de la imagen a firmar.
fields	string	Arreglo JSON de nombres de campos	Todos los campos	Especifica qué campos incluir en la respuesta. Campos disponibles: `sig`, `exp`, `signedUrl`, `imageId` y `requests`. Ejemplo: `?fields=["sig","exp","signedUrl"]`
reuseSignature	boolean	true, false	false	Cuando es true, la API intentará reutilizar una firma generada recientemente para el mismo imageId + variant.

Respuestas

200

Respuesta satisfactoria

400

Error en body o parámetros de la petición

401

Error de autenticación

404

No se encontró algún recurso

429

Demasiadas solicitudes

500

Error inesperado

Eliminar Imagen DELETE

typescript

	import { IOSClient } from '@ircg/ios'
	
	const ios = new IOSClient({ apiKey: API_KEY, lang: 'es' })
	const imageId = 'abc123'
	const result = await ios.delete({ imageId })
	if (result.error) throw new Error(result.error.message)
	console.log(result.success)
	
	const response = await fetch(`https://ircg.dev/api/v1/images/${imageId}`, {
		method: 'DELETE',
		headers: { Authorization: `Bearer ${API_KEY}`, 'Accept-Language': 'es' },
	})
	if (!response.ok) throw new Error(`Delete failed: ${response.status}`)
	console.log(response.status)

Segmento de ruta

https://ircg.dev/api/v1/images/:imageId

Segmento	Tipo	Descripción
imageId	string	El identificador único de la imagen a eliminar.

Respuestas

204

Respuesta satisfactoria (No content)

400

Error en body o parámetros de la petición

401

Error de autenticación

404

No se encontró algún recurso

429

Demasiadas solicitudes

500

Error inesperado

Límites y costos

Cada imagen cargada admite PNG, JPEG, GIF, WebP o SVG y un tamaño máximo de 10 MB.
Se cobran 5 créditos por cada imagen activa en cada ciclo de facturación y 1 crédito por cada imagen servida, sin importar la variante o el tamaño de la respuesta.
Generar o reutilizar una firma de URL no consume créditos.
Los SVG conservan las mismas rutas de variantes y el mismo cobro por solicitud. Se entrega la salida sanitizada; las variantes SVG no se redimensionan aunque la ruta indique un tamaño.
La API autenticada tiene un límite predeterminado de 600 solicitudes por 60 segundos y 15,000 por 3,600 segundos por API key; ambas ventanas se aplican de forma independiente. Puedes solicitar cambios a esos límites desde el panel.
La entrega de imágenes tiene límites independientes y no consume el cupo de la API key: 3,000 solicitudes por 60 segundos por organización y dirección cliente, 30,000 por imagen y 60,000 por organización. Son aproximados por ubicación de entrega; al alcanzarlos, GET y HEAD responden 429 con Retry-After: 60.

Reportar abuso