API Basics

This document covers the common integration approach, 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 documentation.

Overview

The Bach API serves content production, marketing distribution, and creative tooling scenarios, providing end-to-end generation capabilities from creative concept to finished video. Teams can use the API to rapidly 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 large-scale content production.

It fits three typical business scenarios:

• Creative production efficiency: Quickly turn text ideas, script descriptions, or marketing selling points into videos, lowering the production cost from idea to asset.
• Asset animation: Convert existing product photos, portraits, and scene images into dynamic videos, unlocking more content formats from static assets.
• Batch content generation: Combined with asset upload and task query capabilities, business systems can submit generation tasks in bulk — ideal for multi-product, multi-language, multi-style, and multi-channel content production pipelines.

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

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

Basic Information

Endpoint paths in the documentation are typically prefixed with the base URL. For example, for the endpoint POST /videos/text2video, the full request URL is:

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

Authentication

All API requests must include an Authorization header.

Authorization: Bearer <API_TOKEN>

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

Generating a Token

The following Python example 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 = ""  # Your AccessKey
sk = ""  # 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

• Never expose your SecretKey in browsers, mobile clients, or public repositories.
• Generate tokens server-side, and have 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, please refer to the corresponding API documentation.

Example:

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

Asynchronous Task Flow

Generation tasks typically do not return the final result immediately. You first submit a task, then use the task ID to query its progress.

If no callback is configured, the caller should poll the query endpoint for task status. TASK_SUCCEEDED means the task has completed and the result URL or corresponding result field can be read; TASK_FAILED means the task failed and message explains why. Adjust the polling interval to fit your business scenario, task duration, and request quota; in production, we recommend setting a maximum poll count or timeout.

Response Conventions

API responses include 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:

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 has an estimated time available, 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

The task failed to process. 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

The task status indicates the current stage of an asynchronous task. Different endpoints return different result fields, but status semantics are consistent.

For detailed error codes and troubleshooting, see Error Handling.

General Limits

For model capabilities, duration, resolution, frame rate, and other specifications, see the Capability Map.

Error Handling

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

Related Documents

• Capability Map
• Batch Upload
• Using Callbacks