Batch Generation

Batch generation creates one to three barcode images in a single request and returns them in one archive. Each image has its own barcode type, data, image format, and generation settings. For example, a batch can contain a QR code as PNG and a Code 128 barcode as SVG.

Use this operation when you need to download several generated images together. Use the existing single-image generation endpoints when you need one image without an archive.

Endpoint and authentication

POST https://api.aspose.cloud/v4.0/barcode/generate-batch

The OpenAPI operation ID is GenerateBatch. Send an OAuth access token in the Authorization: Bearer <access_token> header, as with other BarCode Cloud generation requests. See Quickstart for account setup and API Explorer authentication for a curl example that obtains a token. The endpoint and request models are described in the OpenAPI specification.

The request body can be JSON (application/json) or XML (application/xml). The successful response is a binary archive, not JSON and not a single image. No Cloud Storage upload is required to receive the archive.

Request parameters

Each generation object must include barcodeType and encodeData, with a non-empty encodeData.data string. The optional encodeData.dataType defaults to StringData; use Base64Bytes to supply binary data as a Base64 string.

The image format is selected separately for each item through generation.barcodeImageParams.imageFormat. Supported values are Png, Jpeg, Svg, Tiff, and Gif. When the image format is omitted, the default is Png.

Optional qrParams, code128Params, and pdf417Params belong inside each item’s generation object. See the JSON/XML generation parameters for image settings and barcode-type-specific options.

Generate two images with JSON

The command examples use Bash syntax. On Windows, run them in Git Bash or WSL.

Save the following request as batch.json. It creates first.png containing a QR code and second.svg containing a Code 128 barcode.

{
  "archiveFormat": "Zip",
  "items": [
    {
      "fileName": "first.png",
      "generation": {
        "barcodeType": "QR",
        "encodeData": {
          "data": "FIRST"
        },
        "barcodeImageParams": {
          "imageFormat": "Png"
        }
      }
    },
    {
      "fileName": "second.svg",
      "generation": {
        "barcodeType": "Code128",
        "encodeData": {
          "data": "SECOND"
        },
        "barcodeImageParams": {
          "imageFormat": "Svg"
        }
      }
    }
  ]
}

Set BARCODE_ACCESS_TOKEN to your access token and submit the request:

: "${BARCODE_ACCESS_TOKEN:?Set your OAuth access token first}"

curl --fail --show-error \
  -H "Authorization: Bearer ${BARCODE_ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  --data-binary @batch.json \
  --output barcodes.zip \
  https://api.aspose.cloud/v4.0/barcode/generate-batch

--data-binary makes this a POST request. The --output option saves the binary response to a file. After a successful HTTP 200 response, inspect the archive:

unzip -l barcodes.zip

The archive contains first.png and second.svg. Changing archiveFormat selects another archive container; it does not change the formats of the images inside it.

Generate two images with XML

Save the following request as batch.xml. XML element names are case-sensitive. Use BatchGenerateRequest as the root, wrap the BatchGenerateItem elements in Items, and use Generation and ArchiveFormat for the generation settings and archive format.

<BatchGenerateRequest>
  <ArchiveFormat>TarGzip</ArchiveFormat>
  <Items>
    <BatchGenerateItem>
      <FileName>first.png</FileName>
      <Generation>
        <BarcodeType>QR</BarcodeType>
        <EncodeData>
          <Data>FIRST</Data>
        </EncodeData>
        <BarcodeImageParams>
          <ImageFormat>Png</ImageFormat>
        </BarcodeImageParams>
      </Generation>
    </BatchGenerateItem>
    <BatchGenerateItem>
      <Generation>
        <BarcodeType>Code128</BarcodeType>
        <EncodeData>
          <Data>SECOND</Data>
        </EncodeData>
        <BarcodeImageParams>
          <ImageFormat>Svg</ImageFormat>
        </BarcodeImageParams>
      </Generation>
    </BatchGenerateItem>
  </Items>
</BatchGenerateRequest>

Send XML with the corresponding content type:

: "${BARCODE_ACCESS_TOKEN:?Set your OAuth access token first}"

curl --fail --show-error \
  -H "Authorization: Bearer ${BARCODE_ACCESS_TOKEN}" \
  -H "Content-Type: application/xml" \
  --data-binary @batch.xml \
  --output barcodes.tar.gz \
  https://api.aspose.cloud/v4.0/barcode/generate-batch

The archive contains first.png and the automatically named barcode-2.svg. You can inspect it with tar -tzf barcodes.tar.gz. Omitting ArchiveFormat selects ZIP, just as omitting archiveFormat does in JSON.

Archive response

The server sends the download file name in the Content-Disposition header. Choose a matching local file extension when saving the response. Renaming a ZIP file to .tar.gz does not convert it to TAR.GZ.

File names inside the archive

File names refer to entries in the returned archive, not paths in Cloud Storage.

• A supplied name is preserved. It may have no extension or an arbitrary extension, such as image.dat.
• The image content is determined by imageFormat, not the file extension. For example, image.dat can contain PNG data.
• An automatic name uses the item’s one-based position and image extension: barcode-1.png, barcode-2.svg, and so on.
• Every resulting name must be unique, ignoring case. This check includes automatic names: a supplied barcode-2.png conflicts with an unnamed second PNG item.
• Supplied names must be no longer than 255 characters. The names . and .., path separators / and \, control characters, and the characters : * ? " < > | are not allowed.

Limits and validation

A batch must contain at least one item and no more than three items. Null items and items without generation are rejected. The server also validates the generation settings for every item.

Batch generation applies the following default resource limits:

Pixel limits use the actual generated dimensions, including automatic sizing and rotation. Exceeding a batch-specific input or output limit returns HTTP 400.

Set resolution with generation.barcodeImageParams.resolution; the default is 96 DPI and the minimum is 1 DPI. The input data limit applies to the encodeData.data string, including the Base64 representation when dataType is Base64Bytes. Image size limits apply before archive compression. One MiB is 1,048,576 bytes.

For more than three images, split the items into separate requests. If a batch exceeds a total pixel or output size limit, reduce the number of items in that request. If a single item exceeds a limit, reduce its data length, image dimensions, or resolution as appropriate before retrying.

The server completes generation and archive creation before returning a successful archive response. If validation or generation fails for any item, the request fails; it does not return an archive containing only the successful items. A failed or interrupted download should not be treated as a valid archive.

Error responses

Errors are not archive responses. Check the HTTP status before opening or extracting a downloaded file. Account-level API usage and restrictions also apply to batch generation.

The curl examples use --fail, which returns a nonzero exit code for HTTP errors and suppresses the error response body. To inspect the API’s error details, repeat the request without --fail, add --dump-header response-headers.txt, and save the response with --output response-body. Check the status and content type in the saved headers before treating the body as an archive.

Calling the endpoint from an SDK

Batch generation can be called with any HTTP client, including HttpClient in .NET; curl is not required. Use the same bearer token and JSON or XML request body as in the examples above.

Language-specific SDK examples will be added after SDK releases that expose the batch operation are available. Until then, do not assume that a method named GenerateBatch or GenerateBatchAsync exists in your installed SDK. Check the SDK version’s API reference or use a direct HTTP request.