API General Guide

This document describes the common access methods, request conventions, response structure, and asynchronous task flow of the Bach API. For specific model capabilities, endpoint parameters, and error codes, please refer to the corresponding documents.

Overview

The Bach API targets content production, marketing delivery, and creative tooling scenarios, providing generation capabilities that take you from creative idea to finished video. Teams can use the API to quickly turn copy, images, product assets, character designs, or multi-element references into video content for ad creatives, social media content, product showcases, creative testing, and batch content production.

It fits three typical business scenarios:

• Creative production efficiency: quickly generate videos from text ideas, script descriptions, or marketing selling points, reducing the cost of going from idea to asset.
• Asset animation: turn existing product images, portrait images, and scene images into dynamic videos, letting static assets produce more content formats.
• Batch content generation: combined with asset upload and task query capabilities, business systems can submit generation tasks in batches, suitable for content production workflows spanning multiple products, languages, styles, and channels.

The core value of the Bach API is not any single model capability, but helping businesses embed video generation into existing workflows: from asset preparation, task submission, and generation processing to result retrieval, everything can be completed automatically by your systems. Operations teams can validate creative directions faster, product teams can integrate video generation capabilities into their own platforms, and engineering teams can access multiple generation capabilities through a unified API.

Simply put, the Bach API can serve as the video generation engine for internal or external products, helping teams produce and test video content at lower cost and higher speed.

Basic Information

Paths in the API documents are typically prefixed with the base URL. For example, when the endpoint path is POST /videos/text2video, the full request URL is:

https://api-gen-na.bach.art/api/vdr/videos/text2video

Authentication

All API requests must carry Authorization in the request headers.

Authorization: Bearer <API_TOKEN>

The API_TOKEN is generated from an AccessKey and a SecretKey. The JWT uses the HS256 signing algorithm and follows the RFC 7519 standard.

Generating a Token

The following example is written in Python and demonstrates how to generate an API Token using the industry-standard JWT Bearer Token approach.

# Python example: generate a JWT Bearer Token
import jwt
from datetime import datetime, timedelta

ak = ""  # Enter your AccessKey
sk = ""  # Enter your SecretKey

def generate_token(ak: str, sk: str) -> str:
    now = datetime.now()

    headers = {
        "alg": "HS256",
        "typ": "JWT",
    }

    payload = {
        "iss": ak,
        "nbf": int((now - timedelta(seconds=5)).timestamp()),
        "exp": int((now + timedelta(days=10)).timestamp()),
    }

    return jwt.encode(payload, sk.encode("utf-8"), headers=headers)

api_token = generate_token(ak, sk)
print(api_token)

Security Recommendations

• Do not expose your SecretKey in browsers, mobile clients, or public repositories.
• We recommend generating the Token on your server, and having your server make requests to the Bach API.
• If authentication fails, first check whether the Token has expired, whether the signature is correct, and whether there is exactly one space between Bearer and the Token.

Request Conventions

This section describes the common rules for all API requests. For specific endpoint parameters, value ranges, and request examples, refer to the corresponding API document.

Example:

curl -X POST '<BASE_URL>/videos/text2video' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -d '{
    "model_name": "bach-1.0",
    "prompt": "Sunset over the sea, camera slowly pushing forward",
    "resolution": "720p",
    "duration": 6
  }'

Asynchronous Task Flow

Generation tasks usually do not return the final result immediately. You need to submit a task first, then query the processing progress using the task ID.

If no callback is configured, the caller should poll the task status via the query endpoint. Polling until TASK_SUCCEEDED means the task has completed and you can read the result URL or the corresponding result field; polling until TASK_FAILED means the task failed and you can check message for the failure reason. The polling interval should be adjusted according to your business scenario, task duration, and request quota; in production environments, we recommend setting a maximum number of polling attempts or a timeout.

Response Conventions

API responses consist of an HTTP status code and a JSON response body.

{
  "code": 200,
  "data": {},
  "timestamp": 1778313600
}

data returns the following fields depending on the endpoint and task status:

Example responses for each status are shown below:

Pending

The task has been submitted and is waiting to be processed.

{
  "code": 200,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "TASK_PENDING",
    "created_at": 1778313600
  },
  "timestamp": 1778313600
}

Processing

The task has started processing. If the system already has an estimate, started_at and estimated_seconds are returned together.

{
  "code": 200,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "TASK_PROCESSING",
    "created_at": 1778313600,
    "started_at": 1778313610,
    "estimated_seconds": 90
  },
  "timestamp": 1778313610
}

Succeeded

The task has completed; the result URL is returned in video_url or the corresponding result field.

{
  "code": 200,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "TASK_SUCCEEDED",
    "created_at": 1778313600,
    "started_at": 1778313610,
    "completed_at": 1778313700,
    "video_url": "https://example.com/result.mp4"
  },
  "timestamp": 1778313700
}

Failed

Task processing failed. If a failure reason is available, it is returned in message.

{
  "code": 200,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "TASK_FAILED",
    "created_at": 1778313600,
    "completed_at": 1778313650,
    "message": "Contains sensitive information."
  },
  "timestamp": 1778313650
}

Task Status

Task status indicates the current stage of an asynchronous task. Different endpoints return different result fields, but the status meanings are the same.

For detailed error codes and troubleshooting, see Error Handling.

General Limits

Error Handling

For detailed error codes, retry recommendations, and troubleshooting, see Error Handling.

Related Documents

• File Upload
• Using Callbacks