WordArt transformation-Alibaba Cloud Model Studio(Model Studio)-阿里云帮助中心

Important

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

WordArt transformation

Note

Supported realm/task: aigc/creative text generation

The WordArt-Text Style Transfer feature creatively transforms input text based on a prompt. This feature enables more creative uses for a single font and returns a black-and-white mask image that contains the text.

Input and sample output

Input text (input.text): Guilin Landscape

Descriptive prompt (input.prompt): Layered mountains, winding Li River, unique rock formations

Result:

Model overview

Model name	Model description
wordart-semantic	The WordArt-Semantic model uses a prompt to creatively change the edges of input text. This process creates many new ways to use a single font. The model returns a white mask image of the text on a black background.

HTTP API call

Feature description

Because this model requires a long processing time, the API uses asynchronous invocation. After you submit a job, the system returns a job ID. You can then use the asynchronous task query API to query the job status and retrieve the result.

Prerequisites

Activate the service and obtain an API key. For more information, see Obtain and configure an API key.

Job submission API call

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

Replace {WorkspaceId} with your actual workspace ID.

Request parameters

Parameter passing	Field	Type	Required	Description	Example
Header	Content-Type	String	Yes	Request type: application/json	application/json
	Authorization	String	Yes	API key. Example: Bearer d1**2a	Bearer d1**2a
	X-DashScope-WorkSpace	String	No	Specifies the workspace for the call. This parameter is required when you use the API key of a RAM user. The RAM user must belong to a workspace. This parameter is optional when you use the API key of an Alibaba Cloud account. If you specify this parameter, the call uses the workspace identity. If you omit this parameter, the call uses the Alibaba Cloud account identity.	ws_QTggmeAxxxxx
	X-DashScope-Async	String	Yes	Always use `enable` to submit jobs asynchronously.	enable
Body	model	String	Yes	Specifies the model to call. This is a static field.	wordart-semantic
	input.text	String	No	The input text.	"text": "Word Art"
	input.prompt	String	Yes	The input prompt. 1 to 200 characters.	"prompt": "Spring blossoms"
	parameters.steps	Integer	No	The number of transformation iterations. A larger number results in a greater degree of text transformation. Valid values: 10 to 100. Default value: 30.	60
	parameters.n	Integer	Yes	The number of images to generate. Default value: 4. Valid values: 1 to 4.	2
	parameters.font_name	String	No	Specifies the font to use. If you do not specify this parameter, the default font Fangzheng Kaiti is used. Available preset fonts: 'dongfangdakai': Alimama Dongfang Dakai 'puhuiti_m': Alibaba PuHuiTi 'shuheiti': Alimama ShuHeiTi 'jinbuti': DingTalk Jinbuti 'kuheiti': ZCOOL KuHei 'kuaileti': ZCOOL KuaiLe 'wenyiti': ZCOOL WenYi 'logoti': ZCOOL XiaoWei LOGO 'cangeryuyangti_m': ZCOOL CangEr YuYang 'siyuansongti_b': Source Han Serif 'siyuanheiti_m': Source Han Sans 'fangzhengkaiti': Fangzheng Kaiti	"font_name": "dongfangdakai"
	parameters.ttf_url	String	No	The user's TTF file. The file must be a standard TTF file smaller than 30 MB. Incompatible with input.text.font_name	"ttf_url":"https://xxxxx"
	parameters.output_image_ratio	String	No	The aspect ratio of the output image. Valid values: "1280x720", "720x1280", and "1024x1024". Default value: "1280x720".	"1280x720"

Response parameters

Field	Type	Description	Example
output.task_id	String	The ID of the asynchronous task for the request. The actual job result must be retrieved through the asynchronous task query API.	13b1848b-5493-4c0e-8c44-68d038b492af
output.task_status	String	The status of the job after the asynchronous task is submitted.	PENDING
request_id	String	The unique ID of the request.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Request example

The following example shows how to use a cURL command to call the model.

Note

Replace <YOUR-DASHSCOPE-API-KEY> with your API key.

Shell

curl --location --request POST 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/wordart/semantic' \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer  <YOUR-DASHSCOPE-API-KEY>' \
--data-raw '{
    "model": "wordart-semantic",
    "input": {
        "text": "Word Art",
        "prompt": "Fruits, vegetables, warm color space"
    },
    "parameters": {
        "steps": 80,
        "n": 2,
        "output_image_ratio": "1024x1024",
        "font_name": "dongfangdakai"
    }
}'

Response example

JSON

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

Abnormal response example

If an error occurs when you submit a job request, the output includes a `code` and `message` that indicate the cause of the error.

JSON

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

Job 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 Passing	Field	Type	Required	Description	Example
URL Path	task_id	String	Yes	The ID of the task to query.	13b1848b-5493-4c0e-8c44-68d038b492af
Header	Authorization	String	Yes	API key. Example: Bearer d1**2a	Bearer d1**2a

Response parameters

Field	Type	Description	Example
output.task_id	String	The ID of the queried task.	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	The status of the queried job.	Task statuses: PENDING: The task is in the queue. RUNNING: The task is being processed. SUCCEEDED: The task is successful. Failed UNKNOWN: The job does not exist or its status is unknown.
output.results	Array	If the job is successful, this field contains result objects generated by the model. Each object contains the URL of a generated result.	[ {"png_url":"https://xxx/1.png"}, {"svg_url":"https://xxx/1.svg"} ]
usage.image_count	Int	The number of images generated for this request.	"image_count": 1
request_id	String	The unique ID of the request.	7574ee8f-38a3-4b1e-9280-11c33ab46e51

Request example

The following example shows how to use a cURL command to call the model.

Note

Replace <YOUR-DASHSCOPE-API-KEY> with your API key.

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 a job is submitted, it is queued. Once the job is scheduled, its status changes to RUNNING. The `task_metrics` field provides the batch processing status.

JSON

{
    "request_id":"e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output":{
        "task_id":"86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status":"RUNNING",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    }
}

Response example (job succeeded)

If a job completes successfully, querying its status returns both the final status and the job result. For this model, the job status is retained for 24 hours. After 24 hours, the job and its results are purged from the system. The job result is a URL for the generated image. For security reasons, this URL is also valid for only 24 hours. Use or save the result promptly after you retrieve it.

JSON

{
    "output":{
        "task_id":"a8532587-fa8c-4ef8-82be-0c46b17950d1",
		"task_status":"SUCCEEDED",
        "results":[
            {
                "png_url":"https://xxx/1.png",
                "svg_url":"https://xxx/1.svg"
            },
            {
                "png_url":"https://xxx/2.png",
                "svg_url":"https://xxx/2.svg"
            },
            {
                "code": "DataInspectionFailed",
                "message": "The output image may contain inproprate content. "
            },
            {
                "png_url":"https://xxx/4.png",
                "svg_url":"https://xxx/4.svg"
            }
        ]
    },
    "usage":{
        "image_count":3
    },
    "request_id":"7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

Response example (job failed)

If a job fails for any reason, its status is set to FAILED. The `code` and `message` fields indicate the cause of the failure.

JSON

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

Status codes

For information about common status codes for the large model service platform, see Error Codes.

This model also has the following specific error codes:

HTTP return code*	Error code (code)	Error message (message)	Description
400	InvalidParameter	The request is missing required parameters or a parameter value is out of the specified range. Check the parameters in your request.	The request is missing required API call parameters or the parameters are out of range.