Batch Upload

Description

The Batch Upload API uploads local image files or image URLs in bulk to Bach storage and returns image URLs that can be used with the generation endpoints. You can use this tool to prepare the image URLs required by image_url, image_urls, or reference_inputs before calling endpoints such as Image to Video or Elements to Video. It is designed for consolidating asset processing before generation, reducing failures caused by inaccessible image URLs, inconsistent formats, or oversized files.

Use Cases

• Upload local images to obtain HTTP/HTTPS image URLs usable in the API.
• Re-host existing image URLs in bulk as stable, accessible asset URLs.
• Prepare image assets before calling the Image to Video API or the Elements to Video API.

Endpoint Information

The full request URL consists of the base URL and the endpoint path; see API Basics.

Upload Limits

Upload via URL

The URL method is suitable for uploading images that are already accessible online; the system re-hosts these images as image URLs usable in the generation endpoints.

Request Parameters

Constraints: images must not be empty and supports up to 300 items; each image is limited to 10 MB; the image URL must contain a recognizable file extension.

Request Example

curl -X POST '<BASE_URL>/batch-upload/submit' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -d '{
    "upload_type": "url",
    "batch_id": "product-images-001",
    "images": [
      {
        "image_data": "https://example.com/images/product-1.jpg",
        "image_name": "product-1.jpg"
      },
      {
        "image_data": "https://example.com/images/product-2.png",
        "image_name": "product-2.png"
      }
    ]
  }'

Success Response

{
  "code": 200,
  "data": {
    "batch_id": "product-images-001",
    "total_count": 2,
    "message": "Batch upload task submitted. please use batch id to query upload progress.",
    "status": "TASK_PENDING"
  },
  "timestamp": 1778313600
}

Upload via Files

The file method is suitable for directly uploading local image files. This endpoint uses multipart/form-data; set the file upload Content-Type accordingly here.

Request Parameters

Constraints: files must not be empty; each file is limited to 10 MB; when image_names is provided, its length must match the number of files.

Request Example

curl -X POST '<BASE_URL>/batch-upload/submit-with-files' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -F 'files=@/path/to/product-1.jpg' \
  -F 'files=@/path/to/product-2.png' \
  -F 'image_names=product-1.jpg' \
  -F 'image_names=product-2.png' \
  -F 'batch_id=product-images-002'

Success Response

{
  "code": 200,
  "data": {
    "batch_id": "product-images-002",
    "total_count": 2,
    "message": "Batch file upload task submitted, please use batch id to query upload progress.",
    "status": "TASK_PENDING"
  },
  "timestamp": 1778313600
}

Query Upload Status

Path Parameters

Request Example

curl -X GET '<BASE_URL>/batch-upload/status/product-images-001' \
  -H 'Authorization: Bearer <API_TOKEN>'

Processing Response

{
  "code": 200,
  "data": {
    "batch_id": "product-images-001",
    "total_count": 2,
    "processed_count": 1,
    "success_count": 1,
    "failed_count": 0,
    "pending_count": 1,
    "status": "TASK_PROCESSING"
  },
  "timestamp": 1778313660
}

Completed Response

{
  "code": 200,
  "data": {
    "batch_id": "product-images-001",
    "total_count": 2,
    "processed_count": 2,
    "success_count": 2,
    "failed_count": 0,
    "pending_count": 0,
    "status": "TASK_SUCCEEDED",
    "results": [
      {
        "index": 0,
        "image_name": "product-1.jpg",
        "image_url": "https://example.com/uploaded/product-1.jpg",
        "status": "TASK_SUCCEEDED"
      },
      {
        "index": 1,
        "image_name": "product-2.png",
        "image_url": "https://example.com/uploaded/product-2.png",
        "status": "TASK_SUCCEEDED"
      }
    ]
  },
  "timestamp": 1778313700
}

Status Reference

Notes

• The image_url values returned by Batch Upload can be used with any endpoint that requires image URLs, such as Image to Video and Elements to Video.
• results is only returned once every image in the batch has finished processing; while processing, use processed_count, success_count, failed_count, and pending_count to gauge progress.
• results[].index corresponds to the order of images or files at submission time, making it easy to map returned URLs back to the original assets.
• For the error structure and general troubleshooting, see Error Handling.

Related Documents

• API Basics
• Capability Map
• Image to Video API
• Elements to Video API
• Error Handling