Text to Subject

Text-to-Subject Image Generation

Generate multi-angle reference images from text descriptions. These images are optimized for use as subject references in the Multi-Image-to-Video endpoint, enabling consistent character and object representation across video frames.


Overview

The Text-to-Subject API takes a text description and generates four reference images showing the subject from different perspectives (front, side, back, and three-quarter views). These images can then be passed directly to the Multi-Image-to-Video endpoint for visually consistent video generation.


Create a Text-to-Subject Task

Generate subject reference images from a text description.

Request URL

Copy
POST https://api-gen-na.bach.art/api/vdr/subject/text2image

Request Headers

HeaderValue
AuthorizationBearer <your_api_token>
Content-Typeapplication/json

Request Body

json
Copy
{
  "name": "Cyber Warrior",
  "description": "Futuristic warrior with glowing neon armor",
  "style": "realistic",
  "subject_type": "character"
}

Request Parameters

ParameterTypeRequiredDefaultDescription
namestringYesSubject identifier name (1–50 characters)
descriptionstringYesDetailed description of the subject's appearance (1–1,000 characters)
stylestringNo"realistic"Rendering style. See Style Options
subject_typestringNo"character"Subject category. See Subject Type Options

Style Options

ValueDescriptionRecommended For
realisticPhotorealistic rendering with natural lighting and texturesLive-action videos, product visualization
animeJapanese animation style with characteristic featuresAnime-style content, manga adaptations
cartoonWestern cartoon style with bold outlines and vivid colorsAnimated content, children's media
3d3D-rendered appearance with depth and shadingGame cinematics, 3D animation
pixelPixel art style with retro aestheticsRetro games, nostalgic content

Subject Type Options

ValueDescriptionExamples
characterLiving beings, humanoids, creaturesWarriors, animals, fantasy creatures, robots
objectInanimate items, props, vehiclesWeapons, furniture, vehicles, artifacts

Response

Success (HTTP 200):

json
Copy
{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "create_at": 1704067200
  }
}
FieldTypeDescription
codeintegerBusiness response code
messagestringResponse message
data.task_idstringUnique task identifier (UUID)
data.create_atlongTask creation timestamp (Unix epoch, seconds)

Error Examples:

ScenarioHTTP StatusCodeMessage
Missing name4001000Name is required.
Invalid style4001000Style must be one of: realistic, anime, cartoon, 3d, pixel
Sensitive content4031250Contains sensitive information.
Queue limit exceeded4001200Queue limit exceeded.
Insufficient credits4001201Insufficient credits.

Query a Text-to-Subject Task

Retrieve the status and generated images of a text-to-subject task.

Request URL

Copy
GET https://api-gen-na.bach.art/api/vdr/subject/text2image/{id}

Request Headers

HeaderValue
AuthorizationBearer <your_api_token>

Path Parameters

ParameterTypeRequiredDescription
idstringYesTask identifier returned by the creation endpoint

Request Example

bash
Copy
curl -X GET "https://api-gen-na.bach.art/api/vdr/subject/text2image/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer <your_api_token>"

Response

Success (HTTP 200):

json
Copy
{
  "code": 200,
  "message": "Success",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "TASK_SUCCEEDED",
    "split_images": {
      "top_left": "https://cdn.example.com/top_left.jpg",
      "top_right": "https://cdn.example.com/top_right.jpg",
      "bottom_left": "https://cdn.example.com/bottom_left.jpg",
      "bottom_right": "https://cdn.example.com/bottom_right.jpg"
    }
  }
}

Response Fields

FieldTypeDescription
data.task_idstringUnique task identifier
data.messagestringCurrent task status
data.split_imagesobjectGenerated reference images. Present only when status is TASK_SUCCEEDED
data.split_images.top_leftstringImage URL — front view
data.split_images.top_rightstringImage URL — side view
data.split_images.bottom_leftstringImage URL — back view
data.split_images.bottom_rightstringImage URL — three-quarter view

Task Status Values

StatusDescription
TASK_PENDINGTask is queued, awaiting processing
TASK_PROCESSINGImage generation is in progress
TASK_SUCCEEDEDGeneration completed; split_images is available
TASK_FAILEDGeneration failed

Task Not Found (HTTP 404):

json
Copy
{
  "code": 1200,
  "message": "Invalid request.The requested resource does not exist or is not available"
}

Integration with Multi-Image-to-Video

The generated subject images are designed for seamless use with the Multi-Image-to-Video endpoint. Pass the four output images as a URL array, paired with a matching subject entry:

Copy
Text-to-Subject API
        │
        │  "Cyber Warrior with neon armor"
        ▼
  ┌────────────┬────────────┐
  │  top_left   │  top_right  │
  │  (front)    │  (side)     │
  ├────────────┼────────────┤
  │ bottom_left │bottom_right │
  │  (back)     │ (3/4 view)  │
  └────────────┴────────────┘
        │
        ▼
Multi-Image-to-Video API
  image_url: [
    "background.jpg",
    [top_left, top_right, bottom_left, bottom_right],
    "foreground.jpg"
  ]
        │
        ▼
  Video with consistent character appearance

Code Examples

Python

python
Copy
import requests
import time

API_BASE = "https://api-gen-na.bach.art/api/vdr"
API_TOKEN = "<your_api_token>"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

# Step 1: Generate subject reference images
payload = {
    "name": "Cyber Warrior",
    "description": "Futuristic warrior wearing glowing neon blue armor with a sleek helmet, "
                   "cybernetic enhancements visible on arms, standing in a confident pose",
    "style": "realistic",
    "subject_type": "character"
}

response = requests.post(
    f"{API_BASE}/subject/text2image",
    headers=headers,
    json=payload
)

task_id = response.json()["data"]["task_id"]
print(f"Task submitted: {task_id}")

# Step 2: Poll for completion
while True:
    status_response = requests.get(
        f"{API_BASE}/subject/text2image/{task_id}",
        headers=headers
    )

    result = status_response.json()["data"]
    status = result["message"]

    if status  "TASK_SUCCEEDED":
        print("Subject images generated:")
        for position, url in result["split_images"].items():
            print(f"  {position}: {url}")
        break
    elif status  "TASK_FAILED":
        print("Generation failed")
        break
    else:
        print(f"Status: {status}, waiting...")
        time.sleep(5)

# Step 3: Use generated images in Multi-Image-to-Video
subject_images = result["split_images"]
video_payload = {
    "image_url": [
        "https://example.com/background.jpg",
        [
            subject_images["top_left"],
            subject_images["top_right"],
            subject_images["bottom_left"],
            subject_images["bottom_right"]
        ]
    ],
    "prompt": "Cyber Warrior walks through a neon-lit cityscape",
    "duration": 5,
    "resolution": "1080p",
    "subject": [
        {
            "subject_name": "Cyber Warrior",
            "subject_type": "character",
            "subject_style": "realistic"
        }
    ]
}

cURL

bash
Copy
# Create task
curl -X POST "https://api-gen-na.bach.art/api/vdr/subject/text2image" \
  -H "Authorization: Bearer <your_api_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Cyber Warrior",
    "description": "Futuristic warrior with glowing neon armor",
    "style": "realistic",
    "subject_type": "character"
  }'

# Query task status
curl -X GET "https://api-gen-na.bach.art/api/vdr/subject/text2image/{task_id}" \
  -H "Authorization: Bearer <your_api_token>"

Node.js

javascript
Copy
const axios = require('axios');

const API_BASE = 'https://api-gen-na.bach.art/api/vdr';
const API_TOKEN = '<your_api_token>';

const headers = {
  'Authorization': `Bearer ${API_TOKEN}`,
  'Content-Type': 'application/json'
};

async function generateSubjectImages() {
  // Step 1: Create task
  const submitResponse = await axios.post(
    `${API_BASE}/subject/text2image`,
    {
      name: 'Cyber Warrior',
      description: 'Futuristic warrior wearing glowing neon blue armor with a sleek helmet',
      style: 'realistic',
      subject_type: 'character'
    },
    { headers }
  );

  const taskId = submitResponse.data.data.task_id;
  console.log(`Task submitted: ${taskId}`);

  // Step 2: Poll for completion
  while (true) {
    const statusResponse = await axios.get(
      `${API_BASE}/subject/text2image/${taskId}`,
      { headers }
    );

    const { message: status, split_images } = statusResponse.data.data;

    if (status === 'TASK_SUCCEEDED') {
      console.log('Subject images generated:');
      Object.entries(split_images).forEach(([position, url]) => {
        console.log(`  ${position}: ${url}`);
      });
      return split_images;
    } else if (status === 'TASK_FAILED') {
      throw new Error('Generation failed');
    }

    console.log(`Status: ${status}, waiting...`);
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

generateSubjectImages().catch(console.error);

Best Practices

Writing Effective Descriptions

AspectGood ExamplePoor Example
Specificity"A medieval knight in silver plate armor with a red cape and dragon emblem on the chest""A knight"
Visual details"Glowing blue eyes, cybernetic arm with exposed wiring""Looks cool"
Pose & expression"Standing in a heroic pose with arms crossed, confident expression""Standing"
Style consistencyMatch description tone to the selected styleMixing realistic details with cartoon style

Style Selection Guide

Content TypeRecommended Style
Marketing videos, product demosrealistic
Anime / manga contentanime
Children's content, explainerscartoon
Game trailers, tech demos3d
Retro / indie game contentpixel

Subject Naming Conventions

  • Use unique, memorable names that you can reference in video prompts later.
  • Include key visual attributes in the name (e.g., "Fire_Mage", "Blue_Robot", "Golden_Dragon").
  • Avoid generic names such as "Character1" or "Person".
  • Keep names under 50 characters.

Recommended Workflow

  1. Generate subjects first: Create all needed subject references before starting video generation.
  2. Save subject URLs: Store the generated image URLs for reuse across multiple videos.
  3. Match styles: Ensure the subject style matches your intended video aesthetic.
  4. Test with short videos: Verify subject consistency with 1–2 second videos before generating longer content.
Previous
Image to Video
Next
Elements To Video
On this page
Text to Subject | bach.art