This topic describes the input and output parameters for the Wanx text-to-image V1 model.
Model overview
Model overview
Model | Introduction |
|---|---|
wanx-v1 | The Wan text-to-image generation model. Its main features include the following:
|
Model | Unit price | Rate limit (shared by Alibaba Cloud account and RAM users) | Free quota | |
|---|---|---|---|---|
Request per second (RPS) for task submission | Number of concurrent tasks | |||
wanx-v1 | CNY 0.16 per image | 2 | 1 | Free quota: 500 images Valid for 180 days after activation |
Prerequisites
You can call the text-to-image V1 model API over HTTP or using the DashScope SDK.
Before making a call, get an API key and export the API key as an environment variable.
To call the API using the SDK, install the DashScope SDK. The SDK is available for Python and Java.
HTTP invocation
Image models take a long time to process. To prevent timeouts, HTTP calls support only asynchronous result retrieval. Two requests are required:
- Create a task to get a task ID: Send a request to create a task. The response returns a task ID (
task_id). - Query the result using the task ID: Use the task ID from the previous step to query the task status and result. If the task is successful, the response returns an image URL that is valid for 24 hours.
Step 1: Create a task to get a task ID
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/text2image/image-synthesis
Replace {WorkspaceId} with your actual workspace ID.
Request parametersRequest headersContent-Typestring (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.X-DashScope-Async string (Required)Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.X-DashScope-WorkSpace string (Optional)The ID of the Model Studio workspace. Example: llm-xxxx.You can get the Workspace ID.
Details Set this parameter to your Model Studio API key.
For details about Alibaba Cloud accounts and RAM users, see Manage account. Request bodymodelstring (Required)The model name. Example: wanx-v1.input object (Required)The basic input information, such as the prompt.
Properties prompt string (Required)The positive prompt. This describes the elements and visual features that you want in the generated image.This parameter supports both Chinese and English. The maximum length is 800 characters. Each Chinese character or letter is counted as one character. Any excess characters are automatically truncated.Example: A sitting orange cat, happy and cute, realistic and accurate.For tips on using prompts, see Text-to-image prompt guide.negative_prompt string (Optional)The negative prompt. This describes the content that you do not want to see in the image and can be used to constrain the output.This parameter supports both Chinese and English. The maximum length is 500 characters. Any excess characters are automatically truncated.Example: low resolution, error, worst quality, low quality, deformed, extra fingers, bad proportions.ref_img string (Optional)The URL of the reference image. The model generates an image with a similar style based on this image.Image requirements:
object (Optional)The image editing parameters.
Properties style string (Optional)The style of the output image. The following styles are supported:
Enumeration values
string (Optional)The resolution of the output image. The following resolutions are supported:
Enumeration values
integer (Optional)The number of images to generate. The value must be an integer from 1 to 4. The default value is 4.seed integer (Optional)The random number seed, which is used to control the randomness of the generated content. The value must be in the range of [0, 2147483647].If you do not provide a seed, the algorithm automatically generates a random number to use. If you provide a seed, the algorithm generates seeds for n images based on the value of n. For example, if n=4, the algorithm generates images with the seeds seed, seed+1, seed+2, and seed+3.To ensure the generated content is relatively stable, use the same seed value for each request.ref_strength float (Optional)Controls the similarity between the output image and the reference image.The value must be in the range of [0.0, 1.0]. A larger value indicates that the generated image is more similar to the reference image.ref_mode string (Optional)The mode for generating an image based on a reference image. The following modes are supported:
Enumeration values
|
|
Response parametersoutputobjectThe task output information.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes. |
Save the task_id to query the task status and result. |
Step 2: Query the result by task ID
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
Request parametersHeadersAuthorizationstring (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.Path parameterstask_idstring (Required)The ID of the task. |
Replace 86ecf553-d340-4e21-xxxxxxxxx with your actual task_id.If you use a model in the Singapore region, replace |
Response parametersoutputobjectThe task output.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
objectStatistics for the task result.
Properties TOTAL integerThe total number of tasks.SUCCEEDED integerThe number of successful tasks.FAILED integerThe number of failed tasks.array of objectThe list of task results, including image URLs, error messages in case of partial task failure.
Structure stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.objectThe output statistics. Only successful results are counted.
Properties image_count integerNumber of images successfully generated. Billing: Cost = Number of images × Unit price.stringUnique request identifier for tracing and troubleshooting. |
Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly. |
DashScope SDK invocation
Make sure you have installed the latest version of the DashScope SDK. Otherwise, a runtime error may occur. For more information, see Install the SDK.
The DashScope SDK currently supports Python and Java.
The parameter names in the SDK are mostly consistent with those in the HTTP API. The parameter structure varies based on the SDK encapsulation for each language. For parameter descriptions, see HTTP invocation.
Because image model processing can be time-consuming, the underlying service is provided asynchronously. The SDK is encapsulated to support both synchronous and asynchronous invocation methods.
Python SDK invocation
- Synchronous call
- Asynchronous call
Request example
Response example
Java SDK invocation
- Synchronous call
- Asynchronous call
Request example
Response example
Error codes
If a model call fails and returns an error message, see Error messages for a solution.
FAQ
Model billing and rate limiting
Free quota
- Description: The free quota applies only to successfully generated output images. Input images or failed model processing do not consume the free quota.
- How to get: It is automatically granted when you activate Model Studio. Valid for 90 days.
- Account scope: Shared between your Alibaba Cloud account and its RAM users.
- For more details, see Free quota for new users.
- If billing shows a limited-time free trial, the model is in public preview. You cannot use the model after the free quota runs out.
- If a clear unit price is shown — for example, CNY 0.2 per second — the model is commercially available. You must pay after the free quota expires or is fully consumed.
- Billing scope: Charges apply only to successfully generated output images. Other scenarios are not billed.
- Billing method: Billing is applied to your Alibaba Cloud account. RAM users cannot be billed independently. Your Alibaba Cloud account must cover all associated charges. To view billing information, go to the Bills page.
- Recharge: Go to the Expenses and Costs console.
- View invocation metrics: Go to the Monitoring page.
- For more billing questions, see Billing Items.
- Rate limit scope: Shared between your Alibaba Cloud account and its RAM users.