API de generación de imagenes IA - Documentación técnica

Una API para generar imagenes con los modelos de generacion ZPK-ULTRA y Dalle-3

Esta API permite generar imagenes mediante IA en los modelos Zpk-Ultra de ZPK Systems, o bien mediante el modelo Dalle-3 de OpenAI.

A diferencia de la API de OpenAI, la API de ZPK permite usar ambos modelos de generación sin los limites de máximo de imagenes establecidos en la API de OpenAi y además soporta callbacks si no desea mantener la comunicación HTTP abierta durante largos periodos de tiempo.

Esta API no soporta la generación de contenido para adultos ni la generación de contenido visual que pueda resultar violento o ofensivo.

Conectando a la API

Servidor y protocolos para la conexión

Conexión a la API
Servidor:	https://zpk.systems
Esquema:	HTTPS, solo conexiones seguras SSL.
Protocolo:	JSON recomendado Enviando un JSON en el body del request, y especificando una cabecera Content-Type: application/json en el request Si envia ficheros como imágenes o documentos, estos deberán estar codificados en base64. Form-Data no recomendado Formato usado en los formularios web, no recomendado. Al enviar una solicitud tipo form_data puede enviar todos los campos como parámetros POST separados. Sin embargo si la solicitud es muy grande recomendamos que envie el contenido de la peticion en un único campo de texto llamado _json (con un guión bajo). Este parametro especial sera procesado por nuestro backend como si se tratase de una solicitud JSON habitual.

El servidor dónde enviar las solicitudes es https://zpk.systems mediante una conexión HTTPS segura.

El tipo de comunicación recomendado es JSON, en cuyo caso especificaremos en la conexión un Content-Type: application/json, y enviaremos el body de la solicitud como un string JSON válido.

Generando imagenes

POST /api/images/generate

Parámetro

Descripción

application_id

alfanumérico requerido

Una id de aplicación, puede obtener la id de una aplicación haciendo click en 'detalles' en su panel

api_key

alfanumérico requerido

La API KEY de la aplicación que efectúa la llamada a esta API, puede obtenerla en su panel, haciendo click en 'detalles' de una aplicación

prompt

string requerido

Una descripción de la imagen a generar

model

string opcional, por defecto: zpk-ultra

El modelo a usar para la generación de imagenes

zpk-ultra El modelo de generación de ZPK Systems, con un 10% mas de acierto que dalle-3

dall-e-3 El modelo de generación de Open-ai, ligeramente mas económico que zpk ultra, y más economico que en la API de Openai

num

integer opcional, por defecto: 1

El número de imagenes a generar con este prompt. Se soporta un máximo de 20 imagenes.

unique_request_id

string opcional / requerido en conexiones hold

Un string de hasta 16 caracteres identificando esta petición a la API. Si este string no es facilitado, los servidores de ZPK generarán un identificador único para esta petición.

callback_url

string opcional

Una dirección URL a la que notificar la generación de las imagenes de esta petición, vea: callbacks.

connection_type

string opcional, por defecto: fast

El tipo de conexión a la API, fast (recomendado) o hold (no recomendado)

La generación de imagenes es una tarea que puede requerir cierto tiempo en los servidores de ZPK, esto provoca que la generación pueda demorarse una media de 30 segundos.

Usar conexiones largas mediante el método HOLD suele provocar problemas de conectividad, ya que muchos proveedores estan actualmente finalizando de modo automático las conexiones que superan un tiempo de espera establecido.

Nuestra recomendación es que use el método fast, que además le proporcionará información mas precisa sobre el tiempo de espera de generación de una imagen.

Conexión fast

Si establece una conexión de tipo fast, se lanzará la orden de generación y se devolverá una respuesta inmediatamente, la conexión finalizará casi instantaneámente, retornando el control a su aplicación.

Cuando la conexión se cierre retornará un unique_request_id generado por los servidores de ZPK, si no lo facilitó usted en el request, y retornará también un tiempo aproximado de generacion wait_time en segundos.

Transcurrido ese tiempo puede realizar una conexión al endpoint de recogida de imagenes solicitando las imagenes de esa petición específica. Se retornará una lista de las imagenes ya generadas, y en caso de que no esten ya todas generadas usted deberá consultar nuevamente el valor de wait_time para volver a realizar la consulta.

Tenga en cuenta que si esta usando PHP nuestro SDK gestiona automáticamente las conexiones y los tiempos de espera, facilitando la integración.

Conexión hold

Al efectuar este tipo de conexión debera obligatoriamente facilitar un unique_request_id a la API, de este modo si la conexión se interrumpe durante la generación de imagen, usted podrá volver a conectar a la API para solicitar las imagenes generadas.

Si establece una conexión hold, la conexión a la API simplemente esperará hasta que la imagen sea generada, si por algun motivo la conexión es interrumpida, debera reconectar y solicitar la imagen generada anteriormente, vea como hacerlo aquí.

quality

string opcional default: standard

La calidad de la imagen final y el esfuerzo en la interpretación del prompt.

standard

Calidad final de la imagen standard.

hq

Mejor calidad de imagen y mayor esfuerzo computacional en la interpretación del prompt

* Tiene coste extra, consulte precios.

style

string opcional default: vivid

El estilo para la generación de imagen.

vivid	El modo por defecto, crea imagenes mas vividas y vibrantes.
natural	Modo para crear imagenes mas 'puras', sin menos alteración de colores.

resolution

string opcional default: 1024x1024

La resolución de la imagen a crear, se soportan las siguientes resoluciones para ambos modelos:

1024x1024 1024x1792 1792x1024

unique_guard

boleano opcional default: false

El sistema de generación realizará un esfuerzo adicional par que la imagen generada sea única. Adicionalmente, se comprovará en las nuevas imagenes generadas por el modelo tanto para el usuario actual, como para cualquier usuario de ZPK que la imagen resultante de un prompt parecido no sea parecida a ninguna de las imagenes de esta solicitud en mas de un 90% de similaridad, adicionalmente ZPK no usará la imagen para entrenar ningún modelo de IA.

Este parametro no afecta a la calidad final de la imágen generada.

Coste adicional Solicitar unique_guard tiene un coste extra en la petición de 0,003 € por imagen.

Esta opción es especialmente relevante si planea usar la imagen para reclamar derechos de autor sobre ella tras realizar pequeñas modificaciones, minimizando la posibilidad de generación de imagenes similares o idénticas

Respuesta de solicitud de generación

Consultando el tiempo de espera

Estructura de una respuesta

El servidor retornará un JSON, con un boleano success si la solicitud de envío se procesó correctamente.

Adicionalmente en el JSON se retornará la lista de elementos images, y cada elemento contendrá el estado de de generación de la imagen y su tiempo de espera.

Como en el resto de las peticiones a APIS de ZPK Systems, se dispone un parámetro cost indicando el coste total de la solicitud a la API.

Estructura de respuesta
Parámetro	Descripción
success	boleano Un boleano con valor true si se pudo procesar su solicitud. O false, en caso de errores.
unique_request_id	string Un string con un identificador único de esta solicitud, si usted no envió este parametro a la api, sera generado por nuestros sistemas.
images	array Un array que contendrá todas las imagenes que usted solicitó, su estado, y su tiempo de espera si aún no fue generada. Consulte la siguiente tabla para detalles sobre los elementos de este array.
cost	float El coste de la solicitud

Estructura del array *images*
Parámetro	Descripción
num	integer El numero de imagen, 0 para la primera.
generation_status	string El estado actual de la imagen, si esta siendo generada, si ya fue generada, o si ocurrió algun error durante su generación. Puede contenter: generated generating pending error
wait_time	integer El numero de segundos que nuestro sistema estima que faltan para terminar de generar la imagen. En imagenes ya generadas será cero.
error_id	string Un identificador de error si se detectó un problema durante la generación de imagenes. Actualmente solo hay dos posibles errores. CONTENT_POLICY_VIOLATION No se pudo generar la imagen porque el prompt o la imagen resultante del prompt parecen estar violando nuestra política de generación. Posiblemente contenido inadecuado, sexual, ofensivo, o violento. GENERAL_ERROR Ocurrió un error general, posible saturación de los servidores, reintente el envio de esa imagen en concreto transcurridos unos segundos.
image_url	string Una dirección HTTPS dónde descargar la imagen generada.

Ejemplo de respuesta con envío correcto.

En este ejemplo podemos ver la respuesta a la solicitud de generar dos imagenes donde nuestros sisteman han determinado un tiempo de generación aproximado de 32 segundos para una imágen, y 30 segundos para la otra imagen.

Respuesta OK

{
"success": true,
"unique_request_id": "ZPK983ujdsifoj38497",
"images": [
	{
		"num": 0,
		"generation_status": "pending",
		"wait_time": "27"
	},
	{
		"num": 1,
		"generation_status": "pending",
		"wait_time": "27"
	}
],
"cost": 0.003
}

Consultando las imagenes generadas

Tras la espera recomendada, nuestra aplicación podrá consultar el estado de imagenes de esta solicitud, consulte la siguiente sección.

Tenga en cuenta que si usó una conexión de tipo hold esta respuesta puede demorarse varios minutos en caso de solicitar muchas imagenes. La respuesta solo se retornará una vez todas las imagenes hayan sido procesadas.

Ejemplo de respuesta con error general

Ejemplo con un envío incorrecto que NO será procesado.

Respuesta Error

{
   "success": false,
   "errors": [
      {
         "id": "INVALID_PARAMETER",
         "message": "promt has not been set",
		 "on": "prompt"
      }
	]
}

Consultando imagenes generadas

Acceda al estado de generación y descargue imagenes ya generadas

Después de solicitar la generación de imagenes, y mediante el unique_request_id retornado por la API usted debe esperar un tiempo prudencial para la generación de las imagenes del request.

Transcurrido este tiempo puede hacer una solicitud a este endpoint para consultar el estado de generación de las distintas imagenes solicitadas, y descargar aquellas que ya hayan sido generadas.

POST /api/images/check-status
Parámetro	Descripción
application_id	alfanumérico requerido Una id de aplicación, puede obtener la id de una aplicación haciendo click en 'detalles' en su panel
api_key	alfanumérico requerido La API KEY de la aplicación que efectúa la llamada a esta API, puede obtenerla en su panel, haciendo click en 'detalles' de una aplicación
unique_request_id	alfanumérico requerido El unique_request_id que se devolvió en la solicitud de generación.

Estructura de respuesta

Estructura de respuesta
Parámetro	Descripción
success	boleano Un boleano con valor true si se pudo procesar su solicitud. O false, en caso de errores.
images	array de estado de imagenes Un array que contendra una lista de las imagenes y su estado, vea la siguiente tabla donde se detalla la estructura de este array.

Estructura del array *images*
Parámetro	Descripción
num	integer El numero de imagen, 0 para la primera.
generation_status	string El estado actual de la imagen, si esta siendo generada, si ya fue generada, o si ocurrió algun error durante su generación. Puede contenter: generated generating pending error
wait_time	integer El numero de segundos que nuestro sistema estima que faltan para terminar de generar la imagen. En imagenes ya generadas será cero.
error_id	string Un identificador de error si se detectó un problema durante la generación de imagenes. Actualmente solo hay dos posibles errores. CONTENT_POLICY_VIOLATION No se pudo generar la imagen porque el prompt o la imagen resultante del prompt parecen estar violando nuestra política de generación. Posiblemente contenido inadecuado, sexual, ofensivo, o violento. GENERAL_ERROR Ocurrió un error general, posible saturación de los servidores, reintente el envio de esa imagen en concreto transcurridos unos segundos.
image_url	string Una dirección HTTPS dónde descargar la imagen generada.

Callbacks, funcionamiento

Reciba notificaciones de imagenes generadas en su servidor

Cuando una petición de generación incluye el parámetro callback_url los servidores de ZPK enviaran notificaciones del estado de las diferentes imagenes a la url indicada a medida que las imagenes son finalizadas.

Los envios se realizan a la url indicada por metodo POST y son de tipo JSON.

Precios de la generación de imagenes

Esta API se factura por demanda, y usted solo pagará según el número de mensajes analizados. No hay descuentos por volumen porque nuestra API tiene el mejor precio desde el primer request.

Modelo	Calidad	Resolución	Openai	ZPK
ZPK Ultra	Standard	1024x1024	-	0,0380 €
	Standard	1024x1792, 1792x1024	-	0,0780 €
	HQ	1024x1024	-	0,0780 €
	HQ	1024x1792, 1792x1024	-	0,1100 €
DALL·E 3	Standard	1024x1024	0,0400 €	0,0390 €
	Standard	1024x1792, 1792x1024	0,0800 €	0,0790 €
	HQ	1024x1024	0,0800 €	0,0790 €
	HQ	1024x1792, 1792x1024	0,1200 €	0,1170 €

Integración con PHP

SDK en PHP para generar imagenes con IA

ZPK-PHP es una librería de código abierto instalable mediante composer que le permitirá integrar nuestras APIs en su proyecto PHP con un mínimo esfuerzo.

Documentación del SDK para PHP

Instalando ZPK-PHP con composer

Terminal

composer require zpksystems/phpzpk

Ejemplo de request para generar imagenes

generación con PHP


<?php

$application = new zpkApplication('app_id','api_key');
$generator = new zpkImageGenerator( $application );

// Create 3 images
$generator->setPrompt("ninja turtles eating pizza");
$generator->generate(3);

$generator->waitForGeneration();

foreach( $generator->images as $image ){
    if( $image->isGenerated() ){
        echo "Generated image, download url: ".$image->getDownloadUrl().PHP_EOL;
    }else{
        echo "Image cannot be generated. Error: ".$image->getErrorCode().PHP_EOL;
    }
}

Regístrese para probar esta API

Regístrese para obtener crédito gratuito y probar esta y otras APIs de ZPK

Registrarse Acceder