Text to Subject API

Description

The Text to Subject API generates reusable subject images from a name and description. Use name to define the subject's identity, description to describe its appearance, materials, clothing, features, and style, and use style and subject_type to control the generation direction. This endpoint is ideal for creating character, object, or brand IP assets first, then reusing them in endpoints such as the Elements to Video API.

Use Cases

• Create characters, products, props, or brand IP subjects from text.
• Prepare stable character or object references for the Elements to Video API.
• When no ready-made images are available, generate subject images first before moving on to the downstream creative workflow.

Endpoint Information

The full request URL consists of the base URL and the endpoint path; see API Basics.

Create Task

Request Parameters

Constraints: name and description are required; style and subject_type only accept the enum values listed above.

Request Example

curl -X POST '<BASE_URL>/subject/text2image' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -d '{
    "name": "Cyber Warrior",
    "description": "A young warrior in silver futuristic armor with glowing blue circuit patterns, clean background, sharp details",
    "style": "realistic",
    "subject_type": "character"
  }'

Success Response

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

Query Task

Path Parameters

Request Example

curl -X GET '<BASE_URL>/subject/text2image/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer <API_TOKEN>'

Success Response

{
  "code": 200,
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "message": "TASK_SUCCEEDED",
    "split_images": {
      "top_left": "https://example.com/subject_top_left.jpg",
      "top_right": "https://example.com/subject_top_right.jpg",
      "bottom_left": "https://example.com/subject_bottom_left.jpg",
      "bottom_right": "https://example.com/subject_bottom_right.jpg"
    }
  },
  "timestamp": 1778313700
}

Notes

• We recommend that description cover the subject's appearance, colors, materials, clothing, pose, and key identifying features — avoid using only abstract keywords.
• Text to Subject returns subject images that can be reused in the subject input of the Elements to Video API.
• The current query result returns the task status in the message field; for detailed status semantics, see Task Status.

Related Documents

• API Basics
• Capability Map
• Elements to Video API
• Error Handling