Zyng AI API Documentation

Getting Started

Authorization: Bearer {your_api_key}

https://api.zyngai.com

Enterprise User APIs

API Flow

The typical interaction with the enterprise API follows these steps:

1. Enable a Workflow: For a stored workflow (Mode 0), open the workflow in Zyng and enable Enterprise API → Lock. For a conditional workflow (Mode 2), lock the default workflow and every route workflow. For an inline workflow (Mode 1), supply the steps and output settings directly in your request.
2. Submit a Product: Send a POST request to /enterprise/v1/process with your sku_id, images, and chosen workflow mode. The API queues the images and returns a unique Request ID (rid). Save this ID to track the submission.
3. Get Results: Obtain processing results through one of two methods:
   • Polling: Send GET requests to /enterprise/v1/status using the returned rid to check that submission, or sku_id to retrieve the latest status for the product. Check the request status and per-image results for output URLs and errors.
   • Webhook Callbacks: Provide your callback endpoint in webhook_url when submitting the product to receive processing-completion notifications.

Enterprise APIs are available to Tier 2 and Tier 3 customers. To upgrade to an enterprise plan, email contact@zyngai.com to request Tier 2 or Tier 3 access. Once Zyng enables enterprise access for your account, use your API key to authenticate requests. Processing requires an available credit balance. Stored workflows must be locked for enterprise API use, contain at least one node, and have complete output settings.

1. Enable a workflow for enterprise use

Open a configured workflow in the Zyng desktop web app. The Enterprise API control is available for enterprise-enabled accounts. Use it to lock the saved workflow before referencing its ID in an enterprise request.

For Mode 0, use the workflow ID shown in the dialog. For Mode 2, lock the default workflow and every route workflow. Mode 1 supplies its workflow inline and does not require this setup.

Locking makes the workflow read-only in the editor. To edit it, select Enterprise API → Unlock, make your changes, and lock it again before using it in new enterprise requests. The workflow ID in the screenshot is an example; use your own ID.

2. Submit a product

POST/enterprise/v1/process

The following examples are complete request templates. Replace <api_key>, workflow IDs, SKU/image identifiers, and the source image URL with your own values. Each request selects exactly one workflow mode.

Mode 0 · Stored workflow

Use the workflow and output settings already configured in Zyng. Replace <DEFAULT_WORKFLOW_ID> with a workflow enabled for enterprise API access.

curl --request POST "https://api.zyngai.com/enterprise/v1/process" \
  --header "Authorization: Bearer <api_key>" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "sku_id": "SKU-001",
    "force_retry": false,
    "sku_metadata": {
      "product_category": "shirt",
      "gender": "unisex",
      "product_description": "",
      "combo": false
    },
    "images": [
      {
        "image_id": "img_front_001",
        "url": "https://your-image-host.com/product-front.jpg",
        "metadata": {
          "angle": "front",
          "is_primary": true
        }
      }
    ],
    "workflow": {
      "mode": 0,
      "workflow_id": "<DEFAULT_WORKFLOW_ID>"
    },
    "webhook_url": ""
  }'

Mode 1 · Inline workflow

Provide nodes and output settings directly. steps must contain at least one node, each with a non-empty nodeName. Supply nodeParam as an object. outputDetails requires non-empty fileExtension, quality, dpi, and fileSize; the extension must start with a dot.

curl --request POST "https://api.zyngai.com/enterprise/v1/process" \
  --header "Authorization: Bearer <api_key>" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "sku_id": "SKU-001",
    "force_retry": false,
    "sku_metadata": {
      "product_category": "shirt",
      "gender": "unisex",
      "product_description": "",
      "combo": false
    },
    "images": [
      {
        "image_id": "img_front_001",
        "url": "https://your-image-host.com/product-front.jpg",
        "metadata": {
          "angle": "front",
          "is_primary": true
        }
      }
    ],
    "workflow": {
      "mode": 1,
      "steps": [
        {
          "nodeName": "Crop_Face",
          "nodeParam": {}
        },
        {
          "nodeName": "MagicResize",
          "nodeParam": {
            "width": "2400",
            "height": "3286",
            "unit": "0"
          }
        }
      ],
      "outputDetails": {
        "fileExtension": ".png",
        "quality": "95",
        "dpi": "72",
        "fileSize": "-1"
      }
    },
    "webhook_url": ""
  }'

Mode 2 · Conditional workflow

Select stored workflows using image-analysis conditions, with a default workflow when no route matches. Every default and route workflow must be enabled for enterprise API access.

Each route needs at least one condition in all_true or all_false. A condition cannot appear in both lists in the same route. Only the three conditions above are supported.

curl --request POST "https://api.zyngai.com/enterprise/v1/process" \
  --header "Authorization: Bearer <api_key>" \
  --header "Content-Type: application/json" \
  --data-raw '{
    "sku_id": "SKU-001",
    "force_retry": false,
    "sku_metadata": {
      "product_category": "shirt",
      "gender": "unisex",
      "product_description": "",
      "combo": false
    },
    "images": [
      {
        "image_id": "img_front_001",
        "url": "https://your-image-host.com/product-front.jpg",
        "metadata": {
          "angle": "front",
          "is_primary": true
        }
      }
    ],
    "workflow": {
      "mode": 2,
      "default": {
        "workflow_id": "<DEFAULT_WORKFLOW_ID>"
      },
      "routes": [
        {
          "when": {
            "all_true": ["human_detection"],
            "all_false": []
          },
          "workflow_id": "<HUMAN_WORKFLOW_ID>"
        },
        {
          "when": {
            "all_true": ["angle_back"],
            "all_false": ["is_zoomed"]
          },
          "workflow_id": "<BACK_WORKFLOW_ID>"
        }
      ]
    },
    "webhook_url": ""
  }'

Accepted response

All three modes return the same accepted response structure. queued means the request was accepted for asynchronous processing; it does not indicate completion. Save rid to check this request.

{
  "rid": "<REQUEST_ID>",
  "sku_id": "SKU-001",
  "status": "queued",
  "images_queued": {
    "total": 1
  },
  "created_at": "<TIMESTAMP>"
}

3. Check status and retrieve outputs

GET/enterprise/v1/status

Look up a submitted request by rid, or retrieve the latest status for a SKU using sku_id. The examples show these as separate queries.

curl "https://api.zyngai.com/enterprise/v1/status?rid=<REQUEST_ID>" \
  -H "Authorization: Bearer <api_key>"

curl "https://api.zyngai.com/enterprise/v1/status?sku_id=SKU-001" \
  -H "Authorization: Bearer <api_key>"

Completed response example

{
  "rid": "<REQUEST_ID>",
  "sku_id": "SKU-001",
  "status": "completed",
  "created_at": "<TIMESTAMP>",
  "completed_at": "<TIMESTAMP>",
  "results": [
    {
      "image_id": "img_front_001",
      "status": "processed",
      "output_url": "<OUTPUT_IMAGE_URL>",
      "errors": [],
      "metadata": {}
    }
  ]
}

The top-level status describes the request. Each entry in results identifies the input with image_id and includes its image status, output_url, errors, and metadata. The example shows a completed request with a processed image.

Poll with a delay while processing is pending. Use the returned rid to follow the specific submission. Confirm production polling intervals, rate limits, and failure handling with your Zyng contact.