Text Texture Generation-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Important

This document applies only to the China (Beijing) region. Use an API key from this region.

Text Texture Generation

Note

Supported realms or tasks: AIGC or Creative Text Generation

WordArt Jinshu—Text Texture Generation creatively designs input text or text images. It applies materials and textures to text based on prompt content, achieving effects such as 3D materials, scene integration, and light and shadow effects. The result is exquisite, diverse artistic text suitable for use as text posters with backgrounds.

Input content and effect illustration:

Style description: Currently, three main categories are supported: Custom, Preset Styles, and Style Reference Image. The Custom category offers three styles. You can customize texture effects using prompts based on the provided styles. It supports input prompts and font types. The Preset Styles category offers 20 styles. This category provides preset style effects and does not support user-defined input prompts or font types. The Style Reference Image category generates similar texture effects based on a reference image you provide. It supports input prompts and font types. Example images for each style are as follows:

Custom category:

Preset Styles category:

Waterfall (waterfall)

Snow Plateau (snow_plateau)

Primeval Forest (forest)

Sky Roaming (sky)

Chinese Style Architecture (chinese_building)

Fantasy Cartoon (cartoon)

Lego Bricks (lego)

Blooming Flowers (flower)

Acrylic (acrylic)

Marble (marble)

Felt Yarn (felt)

Vintage Oil Painting (oil_painting)

Watercolor (watercolor_painting)

Chinese Painting (chinese_painting)

Gongbi painting (elaborate-style painting)

City Night View (city_night)

Lake and Mountain Scenery (mountain_lake)

Autumn Leaves (autumn_leaves)

Green Dragon Auspice (green_dragon)

Red Dragon Auspice (red_dragon)

Style Reference Image category:

Style Reference Image (ref_image_url)	Generated Result

Scenarios

Poster Text Creation: Focus on poster text design. Intelligently generate creative glyphs, artistic textures, and personalized fonts using simple prompt descriptions. Batch-generate rich and engaging personalized posters featuring special-effect artistic text.
Document WordArt Creation: Support WordArt creation and design in office documents. Batch-generate personalized fonts with special-effect artistic text for embedding into documents, enabling diverse content creation.
Creative Marketing with Text Illustrations: Apply to E-commerce, interactive entertainment, video production, and other pan-entertainment scenarios. Generate artistic textures and personalized fonts for intelligent illustrations based on scene themes and specific prompt descriptions.

Features and Benefits

Flexible Creative Font Creation: Intelligently create creative glyphs, artistic textures, and personalized fonts using simple and flexible prompt descriptions.
Diverse Text Edge Styles: Creatively transform the edge contours of input text based on prompt content.
Stable Batch Effect Generation: Batch-generate rich and engaging special-effect artistic text. Achieve precise, controllable recognition, creativity, and artistry of text.
Rapid Transparent Text Generation: Supports generating artistic text images with alpha channels. Enables fine-grained segmentation of artistic text for output as independent assets.
Easy Generation of Similar Styles: Supports inputting style reference images. Easily generate artistic text effects similar to the reference image.

Model Overview

Model Name	Model Description
wordart-texture	WordArt Jinshu - Text Texture Generation creatively designs input text or text images. It adds materials and textures to text based on prompt content, achieving effects such as 3D materials, scene integration, and light and shadow effects. This generates exquisite and diverse artistic text, which can be used directly as text posters with a background.

Input Limits

The text texture service supports two input modes: image input and text input. The field for image input is input.image, and the field for text input is input.text. Choose one of these input methods.
Image input requirements: black background with white text; image size less than 5 MB; recommended formats are JPG, PNG, JPEG, or BMP; aspect ratio no greater than 2:1; longest side no greater than 2048 pixels.
Text input requirements:

Fewer than 6 characters and not an empty string "". Supports Chinese characters, Arabic numerals, and English letters.
If providing a TTF file, it must be a standard TTF file smaller than 30 MB. Specify either the input.text.ttf_url or input.text.font_name field.

Prompt length fewer than 200 characters and cannot be "".
URLs cannot contain Chinese characters.

HTTP API Call

Description

This model requires relatively long algorithm processing time. Therefore, the API uses asynchronous invocation for task submission. After submitting a job through the task API, the system returns a corresponding job ID. You can then query the task status using the asynchronous job query API and retrieve the job results after the job reaches its final completed state.

Prerequisites

Activate the service and obtain an API Key: Obtain an API Key and API Host.

Note

API limits: For a single account—including root account and RAM user—the task submission API has a QPS limit of 2. The concurrent task limit is 1.

Job Submission API Call

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/wordart/texture

Replace {WorkspaceId} with your actual workspace ID.

Request Parameters

Parameter Method	Field	Type	Required	Description	Example Value
Header	Content-Type	String	Yes	Request type: application/json	application/json
	Authorization	String	Yes	API Key, for example: Bearer d1**2a	Bearer d1**2a
	X-DashScope-Async	String	Yes	Use 'enable' to indicate asynchronous job submission.	enable
Body	model	String	Yes	Specifies the model to invoke. Static field.	wordart-texture
	input.image	Object	No	Related fields for image input Fields related to image input. Choose either input.image or input.text.
	input.image.image_url	String	No	The URL of the text image. Image requirements: the image must have a black background and white text, must be less than 5 MB, must have an aspect ratio no greater than 2, and must have a maximum dimension less than or equal to 2048 pixels; recommended image formats are JPG, PNG, JPEG, or BMP. If you select input.image, you must specify this field.	"image_url":"https://xxxxx"
	input.text	Object	No	Fields related to text input Fields related to text input. Choose either input.image or input.text.
	input.text.text_content	String	No	The text content entered by the user must be fewer than 6 characters. If you select input.text, this field is required and cannot be an empty string (""). Supports Chinese characters, Arabic numerals, and English letters. The available characters are defined in the TTF file.	"text": "Text creativity"
	input.text.ttf_url	String	No	The TTF file that you provide. A standard TTF file with a size of less than 30 MB. When you use input.text, you must specify either input.text.ttf_url or input.text.font_name.	"ttf_url":"https://xxxxx"
	input.text.font_name	String	No	Use the name of the preset font. When you use input.text, you must specify only one of input.text.ttf_url and input.text.font_name. Defaults to 'dongfangdakai'. Value types and descriptions: 'dongfangdakai': Alimama Dongfang Dakai 'puhuiti_m': Alibaba PuHuiTi 'shuheiti': Alimama ShuHeiTi 'jinbuti': DingTalk JinBuTi 'kuheiti': ZhanKu KuHeiTi 'kuaileti': ZhanKu KuaiLeTi 'wenyiti': ZhanKu WenYiTi 'logoti': ZhanKu XiaoWei LOGO Ti 'cangeryuyangti_m': ZhanKu CangEr YuYangTi 'siyuansongti_b': Source Han Serif 'siyuanheiti_m': Source Han Sans 'fangzhengkaiti': Founder KaiTi	"font_name": "dongfangdakai"
	input.text.output_image_ratio	String	No	The aspect ratio of the image for text input. Aspect ratio of the text input image. Default is "1:1". Optional ratios are: "1:1", "16:9", "9:16".	"output_image_ratio": "1:1"
	input.prompt	String	Yes	Prompt describing the desired creative style of the text texture. Length less than 200 characters, cannot be "".	"prompt": "Fruits, vegetables"
	input.texture_style	String	No	Type of texture style, including two main categories: 'Custom' and 'Preset Styles' (Note: If using 'Style Reference Image' mode, provide the input.ref_image_url field directly, and this field will not take effect). The specific values and descriptions for the two categories are as follows: "Custom" category offers three styles. Users can customize texture effects using prompts based on the provided styles. It supports input prompts (input.prompt) and font types (input.text.ttf_url and input.text.font_name). Value types are as follows: "material": 3D material "scene": Scene integration "lighting": Light and shadow effects "Preset Styles" category offers 20 styles. This category provides preset style effects and does not support user-defined input prompts (input.prompt) or font types (input.text.ttf_url and input.text.font_name). Value types are as follows: "waterfall": waterfall flow "snow_plateau": Snow Plateau "forest": Primeval Forest "sky": Sky Roaming "chinese_building": Chinese Style Architecture "cartoon": Fantasy Cartoon "lego": Lego Bricks "flower": Blooming Flowers "acrylic": Acrylic "marble": Marble "felt": Felt Yarn "oil_painting": Vintage Oil Painting "watercolor_painting": Watercolor "chinese_painting": Chinese Painting "claborate_style_painting": Gongbi Painting "city_night": City Night View "mountain_lake": Lake and Mountain Scenery "autumn_leaves": Autumn Leaves "green_dragon": Green Dragon Auspice "red_dragon": Red Dragon Auspice Default is "material".	"style_type": "material"
	input. ref_image_url	String	No	The URL of the style reference image. If you provide a style reference image, the input.texture_style field is ignored. Image requirements: We recommend using JPG, PNG, JPEG, or BMP image formats. The aspect ratio must be no greater than 2, and the maximum edge length must be no greater than 2048 pixels. If you provide both a prompt and a reference image, we recommend using the reference image to define the style and the prompt to describe the details of the generated image. The prompt should match the style of the reference image. You can use the Qwen Visual Understanding Large Language Model (Qwen-VL) to generate a prompt based on the reference image.	"ref_image_url ":"https://xxxxx"
	parameters.image_short_size	Integer	No	Length of the short side of the generated image. Default is 704. Value range is [512, 1024]. If the input value is not a multiple of 64, the final value will be the largest multiple of 64 not exceeding the input value.	"image_short_size": 512
	parameters.n	Integer	Yes	Number of images to generate. Default is 1. Value range is [1, 4].	"n": 1
	parameters.alpha_channel	Bool	No	Whether to return an image with an alpha channel. The default value is false.	"alpha_channel": false

Response Parameters

{
    "request_id": "54766eb3-ce64-9082-a7f6-7025813d9482",
    "output": {
        "task_id": "91a5933d-6c49-4130-ae30-a14000e37649",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-08-15 10:46:20.054",
        "scheduled_time": "2025-08-15 10:46:20.087",
        "end_time": "2025-08-15 10:46:27.768",
        "results": [
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.jpg"
            },
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx.jpg"
            }
        ],
        "task_metrics": {
            "TOTAL": 2,
            "SUCCEEDED": 2,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 2
    }
}

Field	Type	Description	Example Value
output.task_id	String	Job ID of this asynchronous task request. Retrieve actual job results using the asynchronous task query API.	13b1848b-5493-4c0e-8c44-68d038b492af
output.task_status	String	Job status after submitting the asynchronous task.	PENDING
request_id	String	Unique system ID for this request.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Request Examples

The following examples show scripts for invoking this model using cURL commands.

Note

Replace your-dashscope-api-key with your API Key in the examples for the code to run correctly.

Shell

# Image input
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/wordart/texture' \
--header 'X-DashScope-Async: enable' \
--header 'Authorization: Bearer <YOUR_DASHSCOPE_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "model": "wordart-texture",
    "input": {
        "image": 
        {
            "image_url": "https://dmshared-new.oss-cn-hangzhou.aliyuncs.com/junyan.hjy/wordart/lcy/example.png"
        },
        "prompt": "fruits, vegetables, warm color space",
        "texture_style": "material"
    },
    "parameters": 
    {
        "image_short_size": 704,
        "n": 2,
        "alpha_channel": false
    }
}'


# Text input
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/wordart/texture' \
--header 'X-DashScope-Async: enable' \
--header 'Authorization: Bearer <YOUR_DASHSCOPE_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "model": "wordart-texture",
    "input": {
        "text": 
        {
            "text_content": "Text Creativity",
            "font_name": "dongfangdakai",
            "output_image_ratio": "1:1"
        },
        "prompt": "fruits, vegetables, warm color space",
        "texture_style": "material"
    },
    "parameters": 
    {
        "image_short_size": 704,
        "n": 2,
        "alpha_channel": false
    }
}'

# Input style reference image
curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/wordart/texture' \
--header 'X-DashScope-Async: enable' \
--header 'Authorization: Bearer <YOUR_DASHSCOPE_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
    "model": "wordart-texture",
    "input": {
        "text": 
        {
            "text_content": "Text Creativity",
            "font_name": "dongfangdakai",
            "output_image_ratio": "16:9"
        },
        "prompt": "flowers",
        "ref_image_url": "https://dmshared-new.oss-cn-hangzhou.aliyuncs.com/0ximian/transfer_20230801/new_design/tmp/wordposter/ref_images/flower2.png"
    },
    "parameters": 
    {
        "image_short_size": 704,
        "n": 2,
        "alpha_channel": false
    }
}'

Response Example

JSON

{
    "output": {
		"task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1", 
    	"task_status": "PENDING"
    },
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

Error Response Example

If a job submission request fails, the response indicates the error reason in the code and message fields.

JSON

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

Job Task Status Query and Result Retrieval API

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Replace {WorkspaceId} with your actual workspace ID.

Request Parameters

Parameter Method	Field	Type	Required	Description	Example Value
Url Path	task_id	String	Yes	The task_id of the job to query.	13b1848b-5493-4c0e-8c44-68d038b492af
Header	Authorization	String	Yes	API Key, for example: Bearer d1**2a	Bearer d1**2a

Response Parameters

Field	Type	Description	Example Value
output.task_id	String	Job ID of this asynchronous task request. Retrieve actual job results using the asynchronous task query API.	13b1848b-5493-4c0e-8c44-68d038b492af
output.task_status	String	Status of the queried job.	Task status: PENDING Queued RUNNING Processing Succeeded FAILED Failed UNKNOWN Job does not exist or status is unknown
output.results	Array	If the job succeeds, this contains the model-generated result object. Each object includes the URL of the generated result as requested.	[ {"url":"https://xxx/1.jpg"}, {"url":"https://xxx/2.jpg"} ]
usage.image_count	Int	Image count generated for this request.	"image_count": 1
request_id	String	Unique system ID for this request.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Request Example

The following example shows a script for invoking this model using a cURL command.

Note

Replace YOUR-DASHSCOPE-API-KEY with your API Key in the example for the code to run correctly.

Shell

curl -X GET \
--header 'Authorization: Bearer <YOUR_DASHSCOPE_API_KEY>' \
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-af6e-a0c6a421c010

Response Example (Job in Progress)

After job submission, the job enters a queued state. It transitions to a running state after scheduling. At this point, the job status is RUNNING, and task_metrics provides the specific batch status.

JSON

{
    "request_id":"e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output":{
        "task_id":"86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status":"RUNNING",
        "submit_time": "2025-08-15 10:46:20.054",
        "scheduled_time": "2025-08-15 10:46:20.087",
        "end_time": "2025-08-15 10:46:27.768",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    }
}

Response Example (Job Completed Successfully)

If a job completes successfully, querying its status again returns both the job status and its results. For this model, the job status remains available for customer queries for 24 hours after completion. After 24 hours, the job and its associated results are purged from the system. The job generates image URLs as results. For security reasons, these URLs are valid for download for 24 hours. You must promptly use or save the results as needed after retrieval.

JSON

{

    "output":{
        "task_id":"a8532587-fa8c-4ef8-82be-0c46b17950d1",
		"task_status":"SUCCEEDED",
        "submit_time": "2025-08-15 10:46:20.054",
        "scheduled_time": "2025-08-15 10:46:20.087",
        "end_time": "2025-08-15 10:46:27.768",
        "results":[
            {
                "url":"https://xxx/1.jpg"
            },
            {
                "url":"https://xxx/2.jpg"
            },
            {
                "url":"https://xxx/3.jpg"
            },
            {
                "url":"https://xxx/4.jpg"
            }
        ]
    },
    "usage":{
        "image_count":4
    },
    "request_id":"7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

Response Example (Job Failed)

If a job fails for any reason, its status is set to FAILED, and the code and message fields indicate the error reason.

JSON

{
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51",
  	"output": {
      "task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1", 
    	"task_status": "FAILED",
    	"code": "xxx", 
    	"message": "xxxxxx" 
    }  
}

Status Code Description

For general status codes of the Large Language Model (LLM) service platform, see: Error Messages

This model also has the following specific error codes:

HTTP Return Code*	Error Code (code)	Error Message (message)	Meaning
400	InvalidParameter	The request is missing required parameters or the parameters are out of the specified range, please check the parameters that you send	Missing required API call parameters or parameters out of range.