Text to Subject API

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

• Create character, product, prop, or brand IP subjects from text.
• Prepare stable character or object reference assets for the Reference to Video API.
• When no ready-made images are available, generate subject images first, then move into subsequent creative workflows.

Create Task

Endpoint Information

• Protocol: HTTPS
• Endpoint: /subject/text2image
• Method: POST
• Request Format: application/json
• Response Format: application/json

The full request URL is formed by concatenating the base URL and the endpoint path; see API General Guide.

Request Headers

Content-Type

Type: string ｜ Required: Yes ｜ Default: None

Data exchange format. Fixed value: application/json

Authorization

Type: string ｜ Required: Yes ｜ Default: None

Authentication information, Bearer Token scheme. Format: Bearer <API_TOKEN>; note that there is exactly one space between Bearer and <API_TOKEN>.

Request Body

name

Type: string ｜ Required: Yes ｜ Default: None

Subject name.

• Must not exceed 50 Chinese/English characters.

description

Type: string ｜ Required: Yes ｜ Default: None

Subject description.

• Must not exceed 1,000 Chinese/English characters.
• For description, we recommend describing the subject's appearance, colors, materials, clothing, pose, and key identifying features, and avoiding purely abstract terms.

style

Type: string ｜ Required: No ｜ Default: realistic

Subject style. Enum values: realistic, anime, cartoon, 3d, pixel.

subject_type

Type: string ｜ Required: No ｜ Default: character

Subject type. Enum values: character, object.

Request Example

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

Response Body

{
    "code": 200,                                          // Status code; see "Error Handling" for definitions
    "data": {
        "task_id": "550e8400-e29b-41d4-a716-446655440000", // Task ID, generated by the system, used to query the task result later
        "status": "TASK_PENDING",                          // Task status; for enum values see "API General Guide - Task Status"
        "created_at": 1778313600                           // Task creation time, Unix timestamp, unit: seconds (s)
    },
    "timestamp": 1778313600                                // Response time, Unix timestamp, unit: seconds (s)
}

task_id

Type: string

Task ID, generated by the system.

-【Note】Please store it safely; it is used to query the task result.

status

Type: string

Task status; for enum values see API General Guide.

created_at

Type: number

Task creation time, Unix timestamp, unit: seconds (s).

Query Task (Single)

Endpoint Information

• Protocol: HTTPS
• Endpoint: /subject/text2image/{task_id}
• Method: GET
• Request Format: application/json
• Response Format: application/json

Request Headers

Authorization

Type: string ｜ Required: Yes ｜ Default: None

Authentication information, Bearer Token scheme. Format: Bearer <API_TOKEN>; note that there is exactly one space between Bearer and <API_TOKEN>.

Path Parameters

task_id

Type: string ｜ Required: Yes ｜ Default: None

The Text to Subject task ID.

-【Note】This is a path parameter; fill the value directly into the request path. Its value is the task_id returned by the create-task endpoint.

Request Example

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

Response Body

{
    "code": 200,                                                       // Status code; see "Error Handling" for definitions
    "data": {
        "task_id": "550e8400-e29b-41d4-a716-446655440000",              // Task ID, generated by the system
        "status": "TASK_SUCCEEDED",                                    // Current task status
        "split_images": {                                               // Returned on successful generation, containing four subject images
            "top_left": "https://example.com/subject_top_left.jpg",     // Top-left image URL
            "top_right": "https://example.com/subject_top_right.jpg",   // Top-right image URL
            "bottom_left": "https://example.com/subject_bottom_left.jpg",   // Bottom-left image URL
            "bottom_right": "https://example.com/subject_bottom_right.jpg"  // Bottom-right image URL
        }
    },
    "timestamp": 1778313700                                             // Response time, Unix timestamp, unit: seconds (s)
}

task_id

Type: string

Task ID, generated by the system.

status

Type: string

Task status; for enum values see API General Guide.

split_images

Type: object

Returned on successful generation, containing four subject images.

• The Text to Subject API returns subject images, which can be used further in the subject input of the Reference to Video API.

split_images.top_left

Type: string

Top-left image URL.

split_images.top_right

Type: string

Top-right image URL.

split_images.bottom_left

Type: string

Bottom-left image URL.

split_images.bottom_right

Type: string

Bottom-right image URL.