File Uploads

Batch Uploads

The Batch Uploads API uploads local images or image URLs in batches to Bach storage and returns image URLs that can be used in the generation endpoints. You can use this tool to prepare the image addresses needed in image_url, image_urls, or reference_inputs before calling Image to Video, Reference to Video, and other endpoints. This endpoint is suited to processing assets uniformly before formal generation, reducing generation failures caused by inaccessible image addresses, inconsistent formats, or oversized files.

  • Upload local images as HTTP/HTTPS image URLs usable in the API.
  • Re-store existing image URLs in batches as stable, accessible asset addresses.
  • Prepare image assets before calling the Image to Video API or the Reference to Video API.

The full request URL is formed by concatenating the base URL and the endpoint path; see API General Guide.

Upload Limits

  • Images per batch: up to 300
  • Size per image: up to 10 MB
  • Supported formats: jpg, jpeg, png
  • Supported MIME types: image/jpeg, image/png

URL Upload

The URL method is suited to uploading image addresses that are already accessible online; the system re-stores these images as image URLs usable in the generation endpoints.

Endpoint Information

  • Protocol: HTTPS
  • Endpoint: /batch-upload/submit
  • Method: POST
  • Request Format: application/json
  • Response Format: application/json

Request Headers

Content-Type

Type: string ｜ Required: Yes ｜ Default: None

Data exchange format. Fixed value: application/json

Authorization

Type: string ｜ Required: Yes ｜ Default: None

Authentication information, Bearer Token scheme. Format: Bearer <API_TOKEN>; note that there is exactly one space between Bearer and <API_TOKEN>.

Request Body

upload_type

Type: string ｜ Required: Yes ｜ Default: None

Upload method. Enum values: url,base64.

images

Type: array ｜ Required: Yes ｜ Default: None

Image list

  • Up to 300 images.

images[].image_data

Type: string ｜ Required: Yes ｜ Default: None

Image URL

  • Must be an HTTP/HTTPS address in a supported format.

images[].image_name

Type: string ｜ Required: No ｜ Default: Empty

Custom image name

  • Generated by the system if not provided.

batch_id

Type: string ｜ Required: No ｜ Default: Empty

Custom batch ID

  • Generated by the system if not provided.

Request Example

bash
Copy
curl --location --request POST '<BASE_URL>/batch-upload/submit' \
--header 'Authorization: Bearer <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "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"
        }
    ]
}'

Response Body

json
Copy
{
    "code": 200,                                          // Status code; see "Error Handling" for definitions
    "data": {
        "batch_id": "product-images-001",                  // Batch ID, used to query upload status and results
        "total_count": 2,                                  // Number of images submitted in this request
        "message": "Batch upload task submitted. please use batch id to query upload progress.",  // Submission note
        "status": "TASK_PENDING"                           // Batch status, see "Status Description"
    },
    "timestamp": 1778313600                                // Response time, Unix timestamp, unit: seconds (s)
}

batch_id

Type: string

Batch ID, used to query upload status and results.

total_count

Type: integer

Number of images submitted in this request.

message

Type: string

Submission note.

status

Type: string

Batch status, see API General Guide.

File Upload

The file method is suited to uploading local image files directly. This endpoint uses multipart/form-data; handle the file upload's Content-Type here.

Endpoint Information

  • Protocol: HTTPS
  • Endpoint: /batch-upload/submit-with-files
  • Method: POST
  • Request Format: multipart/form-data
  • Response Format: application/json

Request Headers

Content-Type

Type: string ｜ Required: Yes ｜ Default: None

Data exchange format. Fixed value: multipart/form-data

Authorization

Type: string ｜ Required: Yes ｜ Default: None

Authentication information, Bearer Token scheme. Format: Bearer <API_TOKEN>; note that there is exactly one space between Bearer and <API_TOKEN>.

Request Body

files

Type: File[] ｜ Required: Yes ｜ Default: None

Array of image files, up to 300.

image_names

Type: string[] ｜ Required: No ｜ Default: Empty

Array of custom image names; if provided, the count must match files.

batch_id

Type: string ｜ Required: No ｜ Default: Empty

Custom batch ID; generated by the system if not provided.

Request Example

bash
Copy
curl --location --request POST '<BASE_URL>/batch-upload/submit-with-files' \
--header 'Authorization: Bearer <API_TOKEN>' \
--form 'files=@/path/to/product-1.jpg' \
--form 'files=@/path/to/product-2.png' \
--form 'image_names=product-1.jpg' \
--form 'image_names=product-2.png' \
--form 'batch_id=product-images-002'

Response Body

json
Copy
{
    "code": 200,                                          // Status code; see "Error Handling" for definitions
    "data": {
        "batch_id": "product-images-002",                  // Batch ID, used to query upload status and results
        "total_count": 2,                                  // Number of images submitted in this request
        "message": "Batch file upload task submitted, please use batch id to query upload progress.",  // Submission note
        "status": "TASK_PENDING"                           // Batch status, see "Status Description"
    },
    "timestamp": 1778313600                                // Response time, Unix timestamp, unit: seconds (s)
}

Query Upload Status

Endpoint Information

  • Protocol: HTTPS
  • Endpoint: /batch-upload/status/{batch_id}
  • Method: GET
  • Request Format: application/json
  • Response Format: application/json

Request Headers

Authorization

Type: string ｜ Required: Yes ｜ Default: None

Authentication information, Bearer Token scheme. Format: Bearer <API_TOKEN>; note that there is exactly one space between Bearer and <API_TOKEN>.

Path Parameters

batch_id

Type: string ｜ Required: Yes ｜ Default: None

The batch ID returned when the upload task was submitted.

【Note】This is a path parameter; fill the value directly into the request path.

Request Example

bash
Copy
curl --location --request GET '<BASE_URL>/batch-upload/status/product-images-001' \
--header 'Authorization: Bearer <API_TOKEN>'

Processing Response

json
Copy
{
    "code": 200,                                          // Status code; see "Error Handling" for definitions
    "data": {
        "batch_id": "product-images-001",                  // Batch ID
        "total_count": 2,                                  // Total number of images in this batch
        "processed_count": 1,                              // Number of images processed
        "success_count": 1,                                // Number of successful uploads
        "failed_count": 0,                                 // Number of failed uploads
        "pending_count": 1,                                // Number of pending images
        "status": "TASK_PROCESSING"                        // Batch status, see "Status Description"
    },
    "timestamp": 1778313660                                // Response time, Unix timestamp, unit: seconds (s)
}

Completed Response

json
Copy
{
    "code": 200,                                          // Status code; see "Error Handling" for definitions
    "data": {
        "batch_id": "product-images-001",                  // Batch ID
        "total_count": 2,                                  // Total number of images in this batch
        "processed_count": 2,                              // Number of images processed
        "success_count": 2,                                // Number of successful uploads
        "failed_count": 0,                                 // Number of failed uploads
        "pending_count": 0,                                // Number of pending images
        "status": "TASK_SUCCEEDED",                        // Batch status, see "Status Description"
        "results": [                                       // Returned after all images have been processed
            {
                "index": 0,                                                // Index of the image in the request list, starting from 0
                "image_name": "product-1.jpg",                             // Image name
                "image_url": "https://example.com/uploaded/product-1.jpg", // Image URL after successful upload
                "status": "TASK_SUCCEEDED"                                 // Upload status of the individual image
            },
            {
                "index": 1,
                "image_name": "product-2.png",
                "image_url": "https://example.com/uploaded/product-2.png",
                "status": "TASK_SUCCEEDED"
            }
        ]
    },
    "timestamp": 1778313700                                // Response time, Unix timestamp, unit: seconds (s)
}

batch_id

Type: string

Batch ID.

total_count

Type: integer

Total number of images in this batch.

processed_count

Type: integer

Number of images processed.

success_count

Type: integer

Number of successful uploads.

failed_count

Type: integer

Number of failed uploads.

pending_count

Type: integer

Number of pending images.

status

Type: string

Batch status, see API General Guide.

results

Type: array

  • results is only returned after all images in the batch have been processed; while processing, use processed_count, success_count, failed_count, and pending_count to judge progress.

Returned after all images have been processed.

results[].index

Type: integer

Index of the image in the request list, starting from 0.

  • results[].index corresponds to the order of images or files at submission time, making it easy to match the returned URLs with the original assets.

results[].image_name

Type: string

Image name.

results[].image_url

Type: string

Image URL after successful upload.

  • The image_url returned by batch upload can be used in Image to Video, Reference to Video, and other endpoints that require image URLs.

results[].status

Type: string

Upload status of the individual image.

results[].error_message

Type: string

Returned when the individual image upload fails.

Previous
Text to Subject
Next
—
On this page
File Uploads | bach.art | bach.art