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
POST https://api-gen-na.bach.art/api/vdr/subject/text2image
Request Headers
| Header | Value |
|---|---|
Authorization | Bearer <your_api_token> |
Content-Type | application/json |
Request Body
{
"name": "Cyber Warrior",
"description": "Futuristic warrior with glowing neon armor",
"style": "realistic",
"subject_type": "character"
}
Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | — | Subject identifier name (1–50 characters) |
description | string | Yes | — | Detailed description of the subject's appearance (1–1,000 characters) |
style | string | No | "realistic" | Rendering style. See Style Options |
subject_type | string | No | "character" | Subject category. See Subject Type Options |
Style Options
| Value | Description | Recommended For |
|---|---|---|
realistic | Photorealistic rendering with natural lighting and textures | Live-action videos, product visualization |
anime | Japanese animation style with characteristic features | Anime-style content, manga adaptations |
cartoon | Western cartoon style with bold outlines and vivid colors | Animated content, children's media |
3d | 3D-rendered appearance with depth and shading | Game cinematics, 3D animation |
pixel | Pixel art style with retro aesthetics | Retro games, nostalgic content |
Subject Type Options
| Value | Description | Examples |
|---|---|---|
character | Living beings, humanoids, creatures | Warriors, animals, fantasy creatures, robots |
object | Inanimate items, props, vehicles | Weapons, furniture, vehicles, artifacts |
Response
Success (HTTP 200):
{
"code": 200,
"message": "success",
"data": {
"task_id": "550e8400-e29b-41d4-a716-446655440000",
"create_at": 1704067200
}
}
| Field | Type | Description |
|---|---|---|
code | integer | Business response code |
message | string | Response message |
data.task_id | string | Unique task identifier (UUID) |
data.create_at | long | Task creation timestamp (Unix epoch, seconds) |
Error Examples:
| Scenario | HTTP Status | Code | Message |
|---|---|---|---|
| Missing name | 400 | 1000 | Name is required. |
| Invalid style | 400 | 1000 | Style must be one of: realistic, anime, cartoon, 3d, pixel |
| Sensitive content | 403 | 1250 | Contains sensitive information. |
| Queue limit exceeded | 400 | 1200 | Queue limit exceeded. |
| Insufficient credits | 400 | 1201 | Insufficient credits. |
Query a Text-to-Subject Task
Retrieve the status and generated images of a text-to-subject task.
Request URL
GET https://api-gen-na.bach.art/api/vdr/subject/text2image/{id}
Request Headers
| Header | Value |
|---|---|
Authorization | Bearer <your_api_token> |
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Task identifier returned by the creation endpoint |
Request Example
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):
{
"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
| Field | Type | Description |
|---|---|---|
data.task_id | string | Unique task identifier |
data.message | string | Current task status |
data.split_images | object | Generated reference images. Present only when status is TASK_SUCCEEDED |
data.split_images.top_left | string | Image URL — front view |
data.split_images.top_right | string | Image URL — side view |
data.split_images.bottom_left | string | Image URL — back view |
data.split_images.bottom_right | string | Image URL — three-quarter view |
Task Status Values
| Status | Description |
|---|---|
TASK_PENDING | Task is queued, awaiting processing |
TASK_PROCESSING | Image generation is in progress |
TASK_SUCCEEDED | Generation completed; split_images is available |
TASK_FAILED | Generation failed |
Task Not Found (HTTP 404):
{
"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:
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
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
# 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
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
| Aspect | Good Example | Poor 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 consistency | Match description tone to the selected style | Mixing realistic details with cartoon style |
Style Selection Guide
| Content Type | Recommended Style |
|---|---|
| Marketing videos, product demos | realistic |
| Anime / manga content | anime |
| Children's content, explainers | cartoon |
| Game trailers, tech demos | 3d |
| Retro / indie game content | pixel |
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
- Generate subjects first: Create all needed subject references before starting video generation.
- Save subject URLs: Store the generated image URLs for reuse across multiple videos.
- Match styles: Ensure the subject style matches your intended video aesthetic.
- Test with short videos: Verify subject consistency with 1–2 second videos before generating longer content.