Zyng AI API Documentation

Integrate Zyng AI's powerful image processing capabilities into your applications using our straightforward REST API.

Getting Started

Authentication

All API requests must be authenticated using a Bearer Token. Include your API key in the Authorization header for every request.

Authorization: Bearer {your_api_key}

You can find your API key in your Zyng AI account dashboard: https://app.zyngai.com/account

Rate Limits & Request Queueing

Our API implements intelligent request queueing to ensure reliable processing even during high-volume periods. Unlike traditional rate limiting, requests exceeding your tier's limit are automatically queued rather than rejected.

Tier 1

Generally Available

requests per minute

Shared processing queue

Tier 2

Available on Request

100

requests per minute

Dedicated server & priority queue

Tier 3

Available on Request

1,000

requests per minute

Dedicated server & highest priority queue

Smart Request Queueing

When you exceed your tier's rate limit:

Requests are automatically queued instead of returning errors
All requests receive a successful response with a valid RID
Processing order is maintained based on queue priority
Higher tier customers enjoy faster queue processing

How to Upgrade Your Tier

To request an upgrade to Tier 2 or Tier 3, please email [email protected]. Include your current usage patterns and expected volume to help us better understand your needs. Higher tiers include:

Dedicated processing servers
Priority queue processing
Webhook support
Enhanced support response times

Base URL

All API endpoints are relative to the following base URL:

https://api.zyngai.com

Standard API Flow

The typical interaction with the API follows these steps:

Register Request: Send a POST request to initialize a processing job and receive a unique Request ID (rid). This step defines the workflow and output settings.
Process Image(s): Send one or more POST requests, using the rid obtained in step 1, providing the image URL (imglink) and a unique name for each image (image_name).
Get Results: Obtain processing results through one of two methods:
- Polling Method (All Tiers): Periodically send GET requests using the rid to check processing status and retrieve results.
- Webhook Method (Tier 2 & 3): Receive an automatic POST notification to your specified endpoint when processing completes. No polling required.

Webhook Availability

Webhooks are available for Tier 2 and Tier 3 customers, providing instant notifications when results are ready. See our rate limits section for tier details.

Workflow & Output Parameters

The workflowDetails and outputDetails objects are crucial for defining how your images are processed and where they are delivered. These parameters are dynamic and depend on the specific workflow you configure in the Zyng AI web application.

You can find the exact JSON structure for these parameters within your workflow settings in the Zyng AI app, under "API". Here's where to look:

1. Navigate to your Workflow.

2. Find the API details section.

3. Copy the workflowDetails & outputDetails JSON.

API Endpoints

1. Register Request

Initializes a new processing job session and returns a unique Request ID (rid) required for subsequent image processing calls within that session.

POST /process_image

Headers:

Content-Type: application/json
Authorization: Bearer {your_api_key}

Request Body:

{
    "task": "register_request",
    "workflowDetails": { /* Workflow configuration object from Zyng AI UI */ },
    "outputDetails": { /* Output configuration object from Zyng AI UI */ }
}

- task: Must be set to "register_request".
- workflowDetails: The JSON object defining the processing steps, copied from your Zyng AI workflow settings.
- outputDetails: The JSON object defining output formats and destinations, copied from your Zyng AI workflow settings.

Success Response (200 OK):

{
    "rid": "a_unique_generated_request_id"
}

- rid: The unique identifier for this processing session. Store this ID to use in the next steps.

2. Process Image

Submits a single image for processing under an existing Request ID (rid). You can call this endpoint multiple times with the same rid for batch processing.

POST /process_image

Headers:

Content-Type: application/json
Authorization: Bearer {your_api_key}

Request Body:

{
   "rid": "a_unique_generated_request_id",
   "task": "process_image",
   "imglink": "https://your-image-host.com/path/to/image.jpg",
   "image_name": "product_photo_variant_1",
   "workflowDetails": { /* Same object as in register_request */ },
   "outputDetails": { /* Same object as in register_request */ }
}

- rid: The ID received from the "Register Request" step.
- task: Must be set to "process_image".
- imglink: A publicly accessible URL to the source image.
- image_name: A unique name for this specific image within the request. Used for identifying results.
- workflowDetails: Must be the *exact same* object provided during registration.
- outputDetails: Must be the *exact same* object provided during registration.

Success Response (200 OK):

"Processing Images"

A simple string confirmation indicates the image has been queued for processing.

3. Poll Results

Retrieves the status and results for a processing request identified by its rid. Poll this endpoint periodically until all expected images are processed.

GET /poll_results?rid={rid}

URL Parameters:

- rid (required): The Request ID obtained from the "Register Request" step.

Headers:

Authorization: Bearer {your_api_key}

Success Response (200 OK):

[
    {
        "iid": "https://images.zyngai.com/processed/path/product_photo_variant_1.png",
        "layers": false,
        "name": "product_photo_variant_1.png",
        "rid": "a_unique_generated_request_id"
    },
    {
        "iid": "https://images.zyngai.com/processed/path/product_photo_variant_2.jpg",
        "layers": false,
        "name": "product_photo_variant_2.jpg",
        "rid": "a_unique_generated_request_id"
    }
    // ... more image results if available
]

Returns a JSON array. Each object in the array represents a successfully processed image from the request.
- iid: The URL to the final processed image.
- name: The filename, often derived from the image_name provided during processing.
- rid: The request ID this result belongs to.
- layers: Indicates if layer information is available (typically false unless specifically configured).

Note: The endpoint returns an empty array [] if processing is still ongoing or if no images have completed yet for the given rid. Continue polling until the array contains the expected number of results. Implement appropriate delays and retry logic in your polling mechanism.

Webhook Alternative

For Tier 2 and Tier 3 customers, we offer webhook notifications when processing is complete, eliminating the need for polling. With webhooks, we'll send a POST request to your specified endpoint with the same response format as the polling endpoint when results are ready.