AI Image Generation API - Technical Documentation

An API for generating images using the ZPK-ULTRA and Dalle-3 generation models

This API allows the generation of images using the Zpk-Ultra models from ZPK Systems or the Dalle-3 model from OpenAI.

Unlike the OpenAI API, the ZPK API allows the use of both generation models without the image maximum limits set by the OpenAI API, and it also supports callbacks if you do not want to keep the HTTP communication open for long periods of time.

This API does not support the generation of adult content or the generation of visual content that may be violent or offensive.

API connection

Server and protocols involved.

API connection details
Server:	https://zpk.systems
Scheme:	HTTPS, secure connections only.
Protocol:	JSON recommended Sending a JSON in the request body, and specifying a Content-Type: application/json header in the request Files should be sent encoded as a base64 string. Form-Data not recommended Format used in web forms, not recommended. When sending a form_data request you can send all the fields separately. However if the request is very large we recommend that you send the content of the request in a single text field called _json (with an underscore). This special parameter will be processed by our backend as if it were a regular JSON request.

The server to send the requests to is https://zpk.systems, using a secure HTTPS connection.

The recommended communication type is JSON, in which case we will specify in the connection a Content-Type: application/json, and we will send the request body as a valid JSON string.

Image generation

POST /api/images/generate

Parameter

Description

application_id

alphanumeric required

An application ID; you can obtain the ID of an application by clicking on 'details' in your dashboard.

api_key

alphanumeric required

The API key of the application making the call to this API; you can obtain it in your dashboard by clicking on 'details' for an application.

prompt

string required

A description of the image to generate.

model

string optional, default: zpk-ultra

The model to use for image generation.

zpk-ultra The ZPK Systems generation model, with 10% more accuracy than dalle-3.

dall-e-3 The OpenAI generation model, slightly more economical than zpk-ultra, and more affordable than the OpenAI API.

num

integer optional, default: 1

The number of images to generate with this prompt. A maximum of 20 images is supported.

unique_request_id

string optional / required in hold connections

A string of up to 16 characters identifying this API request. If this string is not provided, ZPK servers will generate a unique identifier for this request.

callback_url

string optional

A URL to notify about the generation of images for this request; see: callbacks.

connection_type

string optional, default: fast

The type of connection to the API, fast (recommended) or hold (not recommended)

Image generation is a task that may take some time on ZPK servers, causing the generation to take an average of 30 seconds.

Using long connections via the HOLD method often leads to connectivity issues, as many providers are currently automatically terminating connections that exceed a set timeout.

Our recommendation is to use the fast method, which will also provide more accurate information about the generation wait time for an image.

Fast Connection

If you establish a fast connection, the generation command will be launched, and a response will be returned immediately; the connection will end almost instantly, returning control to your application.

When the connection closes, it will return a unique_request_id generated by ZPK servers, if you did not provide it in the request, and will also return an approximate generation time wait_time in seconds.

After that time, you can make a connection to the image collection endpoint to request the images from that specific request. It will return a list of the already generated images, and if they are not all generated, you should check the value of wait_time again before making the request.

Please note that if you are using PHP, our SDK automatically manages connections and wait times, facilitating integration.

Hold Connection

When making this type of connection, you must provide a unique_request_id to the API. This way, if the connection is interrupted during image generation, you can reconnect to the API to request the generated images.

If you establish a hold connection, the API connection will simply wait until the image is generated. If for any reason the connection is interrupted, you will need to reconnect and request the previously generated image; see how to do it here.

quality

string optional default: standard

The quality of the final image and the effort in interpreting the prompt.

standard

Standard final image quality.

hq

Better image quality and higher computational effort in interpreting the prompt.

* It has an extra cost; check prices.

style

string optional default: vivid

The style for image generation.

vivid	The default mode, creates more vivid and vibrant images.
natural	Mode to create more 'pure' images, with less color alteration.

resolution

string optional default: 1024x1024

The resolution of the image to create; the following resolutions are supported for both models:

1024x1024 1024x1792 1792x1024

unique_guard

boolean optional default: false

The generation system will make an additional effort to ensure that the generated image is unique. Additionally, it will be checked in the new images generated by the model, both for the current user and for any ZPK user, that the resulting image from a similar prompt is not similar to any of the images from this request by more than 90% similarity. Additionally, ZPK will not use the image to train any AI model.

This parameter does not affect the final quality of the generated image.

Additional Cost Requesting unique_guard incurs an extra cost in the request of 0,003 € per image.

This option is particularly relevant if you plan to use the image to claim copyright over it after making minor modifications, minimizing the possibility of generating similar or identical images.

Generation Request Response

Checking Wait Time

Response Structure

The server will return a JSON with a boolean success indicating whether the submission request was processed successfully.

Additionally, the JSON will include a list of images elements, and each element will contain the status of image generation and its wait time.

As in the rest of the requests to ZPK Systems APIs, there is a cost parameter indicating the total cost of the API request.

Response Structure
Parameter	Description
success	boolean A boolean with a value of true if your request was successfully processed. Or false in case of errors.
unique_request_id	string A string with a unique identifier for this request. If you did not send this parameter to the API, it will be generated by our systems.
images	array An array that will contain all the images you requested, their status, and their wait time if not yet generated. Refer to the following table for details on the elements of this array.
cost	float The cost of the request

Structure of the *images* array
Parameter	Description
num	integer The image number, 0 for the first one.
generation_status	string The current status of the image, whether it is being generated, has already been generated, or if an error occurred during its generation. It can contain: generated generating pending error
wait_time	integer The number of seconds that our system estimates are remaining to finish generating the image. In already generated images, this will be zero.
error_id	string An error identifier if a problem was detected during image generation. Currently, there are only two possible errors. CONTENT_POLICY_VIOLATION The image could not be generated because the prompt or the resulting image from the prompt appears to violate our generation policy. Possibly inappropriate, sexual, offensive, or violent content. GENERAL_ERROR A general error occurred, possibly server saturation. Retry sending that specific image after a few seconds.
image_url	string An HTTPS address where you can download the generated image.

Example of Response with Successful Submission.

In this example, we can see the response to the request to generate two images where our systems have determined an approximate generation time of 32 seconds for one image and 30 seconds for the other image.

Response 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
				}

Checking the Generated Images

After the recommended waiting period, our application can check the status of images from this request, refer to the next section.

Keep in mind that if you used a hold connection, this response may take several minutes in case of requesting many images. The response will only be returned once all images have been processed.

Example of Response with General Error

Example with an incorrect submission that will NOT be processed.

Response Error

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

Checking Generated Images

Access the generation status and download already generated images

After requesting the generation of images, and using the unique_request_id returned by the API, you should wait a reasonable amount of time for the generation of the images from the request.

After this time has passed, you can make a request to this endpoint to check the generation status of the different requested images and download those that have already been generated.

POST /api/images/check-status
Parameter	Description
application_id	alphanumeric required An application ID; you can obtain the ID of an application by clicking on 'details' in your panel.
api_key	alphanumeric required The API KEY of the application making the call to this API; you can obtain it in your panel by clicking on 'details' of an application.
unique_request_id	alphanumeric required The unique_request_id returned in the generation request.

Response Structure

Response Structure
Parameter	Description
success	boolean A boolean with a value of true if your request was processed successfully. Or false in case of errors.
images	array of image status An array that will contain a list of images and their status; see the following table for the structure of this array.

Structure of the *images* array
Parameter	Description
num	integer The image number, 0 for the first one.
generation_status	string The current status of the image, whether it is being generated, has already been generated, or if an error occurred during its generation. It can contain: generated generating pending error
wait_time	integer The number of seconds that our system estimates are remaining to finish generating the image. For already generated images, it will be zero.
error_id	string An error identifier if an issue was detected during image generation. Currently, there are only two possible errors. CONTENT_POLICY_VIOLATION The image could not be generated because the prompt or the resulting image from the prompt seems to violate our generation policy. Possibly inappropriate, sexual, offensive, or violent content. GENERAL_ERROR A general error occurred, possible server saturation; retry sending that particular image after a few seconds.
image_url	string An HTTPS address to download the generated image.

Callbacks, Operation

Receive notifications for images generated on your server

When a generation request includes the callback_url parameter, ZPK servers will send notifications about the status of different images to the specified URL as the images are completed.

The notifications are sent to the specified URL via the POST method and are in JSON format.

Precios de la generación de imagenes

This API is billed on demand, and you will only pay according to the number of analyzed messages. There are no volume discounts because our API offers the best price from the first request.

Model	Quality	Resolution	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 €

Integration with PHP

PHP SDK for Image Generation with AI

ZPK-PHP is an open-source library installable via Composer that will allow you to integrate our APIs into your PHP project with minimal effort.

SDK Documentation for PHP

Installing ZPK-PHP with Composer

Terminal

composer require zpksystems/phpzpk

Example Request for Image Generation

Generation with 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;
    }
}

Signup to try

Login, or Signup for freee to test this API

Register Log in