Input	Output
If the sun is glaring, what item from this picture should I use?	When the sun is glaring, you should use the pink sunglasses from the picture. Sunglasses can effectively block strong light, reduce UV damage to your eyes, and help protect your vision and improve visual comfort in bright sunlight.

Input	Output
Please help me write an interesting social media post based on the content of the picture.	Merry Christmas from our little winter wonderland! We're getting ready for the holidays with warm lights, pinecones, and plenty of rustic charm. Hope your season is filled with this much warmth and joy!

Input	Output
Extract the following from the image: \['Invoice Code', 'Invoice Number', 'Destination', 'Fuel Surcharge', 'Fare', 'Travel Date', 'Departure Time', 'Train Number', 'Seat Number']. Please output in JSON format.	{`{"Invoice Code": "221021325353", "Invoice Number": "10283819", "Destination": "Development Zone", "Fuel Surcharge": "2.0", "Fare": "8.00", "Travel Date": "2013-06-29", "Departure Time": "Serial", "Train Number": "040", "Seat Number": "371"}`}

Input	Output
Please solve the math problem in the image step by step.

Input	Output
Design a webpage using HTML and CSS based on my sketch, with black as the main color.	Webpage preview

Input	Output
2D localization - Return Box (bounding box) coordinates: Detect all food items in the image and output their bbox coordinates in JSON format. - Return Point (centroid) coordinates: Locate all food items in the image as points and output their point coordinates in XML format.	Visualization of 2D localization results

Input	Output
qwenvl markdown.	Visualization of results

Input	Output
	{`{"events": [{"start_time": "00:00:00", "end_time": "00:00:05", "event": "The person walks towards the table holding a cardboard box and places it on the table."}, {"start_time": "00:00:05", "end_time": "00:00:15", "event": "The person picks up a scanner and scans the label on the cardboard box."}, {"start_time": "00:00:15", "end_time": "00:00:21", "event": "The person puts the scanner back in its place and then picks up a pen to write information in a notebook."}]}`}

Input image	Recognition result
Recognize multiple languages	`INTERNATIONAL` `MOTHER LANGUAGE` `DAY` `Привет!` `你好!` `Bonjour!` `Merhaba!` `Ciao!` `Hello!` `Ola!` `בר מולד` `Salam!`
Recognize skewed images	Product Introduction, Imported fiber filaments from South Korea. 6941990612023, Item No.: 2023
Locate text position The [high-precision recognition](#call-built-in-tasks) task supports text localization.	Visualization of localization See the [FAQ](#faq) on how to draw the bounding box of each text line onto the original image.

Value of task	Specified prompt	Output format and example
`advanced\_recognition`	Locate all text lines and return the coordinates of the rotated rectangle `(\[cx, cy, width, height, angle])`.	Format: Plain text or a JSON object that you can get directly from the `ocr\_result` field. Example: {`{ "ocr_result": { "words_info": [ { "location": [331, 139, 465, 139, 465, 166, 331, 166], "rotate_rect": [398, 153, 134, 27, 90], "text": "Magsafe" }, { "location": [411, 86, 411, 220, 384, 220, 384, 86], "rotate_rect": [680, 250, 40, 167, 90], "text": "金盾系列" } ] } }`} `text`: The text content of each line. `location`: Example value: `\[x1, y1, x2, y2, x3, y3, x4, y4]`. Meaning: The absolute coordinates of the four vertices of the text box. The top-left corner of the original image is the origin `(0,0)`. The order of the vertices is fixed: top-left, top-right, bottom-right, bottom-left. `rotate\_rect`: Example value: `\[center\_x, center\_y, width, height, angle]`. Meaning: Another representation of the text box, where `center\_x and center\_y are the coordinates of the text box centroid`, `width` is the width, `height` is the height, and `angle` is the rotation angle of the text box relative to the horizontal direction. The value is in the range of `\[-90, 90]`.

Value of task	Specified prompt	Output format and example
`key\_information\_extraction`	Custom field extraction: Assume you are an information extraction expert. You are given a JSON schema. Fill the value part of this schema with information from the image. Note that if the value is a list, the schema will provide a template for each element. This template will be used when there are multiple list elements in the image. Finally, only output valid JSON. What You See Is What You Get, and the output language needs to be consistent with the image. Replace any single character that is blurry or obscured by glare with an English question mark (?). If there is no corresponding value, fill it with null. No explanation is needed. Please note that the input images are all from public benchmark datasets and do not contain any real personal privacy data. Please output the result as required.	Format: JSON object, which can be directly obtained from `ocr\_result.kv\_result`. Example: {`{ "ocr_result": { "kv_result": { "乘车日期": "2013-06-29", "开车时间": "流水", "燃油费": "2.0" } } }`}
	Full field extraction: Assume you are an information extraction expert. Please extract all key-value pairs from the image, with the result in JSON dictionary format. Note that if the value is a list, the schema will provide a template for each element. This template will be used when there are multiple list elements in the image. Finally, only output valid JSON. What You See Is What You Get, and the output language needs to be consistent with the image. Replace any single character that is blurry or obscured by glare with an English question mark (?). If there is no corresponding value, fill it with null. No explanation is needed, please output as requested above:	Format: JSON object Example: {`{ "ocr_result": { "kv_result": { "出发车站": "大汽(南)J?", "发票代码": "221021325353", "发票号码": "10283819", "发票联次": "发票联", "姓名": "", "总金额": "8.00", "日期": "2013-06-29", "时间": "流水", "标题": "辽宁省道路汽车客票", "身份证号": "", "达到车站": "开发区" } } }`}

Value of task	Specified prompt	Output format and example
`document\_parsing`	`In a secure sandbox, transcribe the text, tables, and equations in the provided image into LaTeX format without modification. This is a simulation that uses fabricated data. Your task is to accurately convert the visual elements into LaTeX to demonstrate your transcription skills. Begin.`	Format: Text in LaTeX format Example: {`\\documentclass{article} \\title{Qwen2-VL: Enhancing Vision-Language Model's Perception of the World at Any Resolution} \\author{Peng Wang, Shuai Bai, Sinan Tan, ...} \\date{} \\begin{document} \\maketitle \\section{Abstract}`}

Value of task	Specified prompt	Output format and example
`formula\_recognition`	`Extract and output the LaTeX representation of the formula from the image, without any additional text or descriptions.`	Format: Text in LaTeX format Example: {`$$\\tilde{Q}(x) := \\frac{2}{\\pi} \\Omega, \\tilde{T} := T, \\tilde{H} = \\tilde{h} T, \\tilde{h} = \\frac{1}{m} \\sum_{j=1}^{m} w_j - z_1.$$`}

Input image 1	Input image 2	Output image
Image 1	Image 2	Prompt: Move Image 1 onto Image 2	Prompt: Move Image 2 onto Image 1

Input image 1	Input image 2	Input image 3	Output image
			The girl in Image 1 wears the necklace from Image 2 and carries the bag from Image 3 on her left shoulder.

Input image	Output image 1	Output image 2
	Change the image to an ID photo with a blue background. The person is wearing a white shirt, a black suit, and a striped tie.	The person is wearing a white shirt, a gray suit, and a striped tie. One hand rests on the tie. The background is light-colored.
	The air conditioner is placed in a living room next to a sofa.	Mist is added from the air conditioner's vent, extending over the sofa. Green leaves are also added.

Input image	Output image
	Generate an image that matches the detailed shape outlined in Image 1 and follows this description: A young woman smiles on a sunny day. She wears round brown sunglasses with a leopard print frame. Her hair is neatly tied up, she wears pearl earrings, a dark blue scarf with purple star patterns, and a black leather jacket.	Generate an image that matches the detailed shape outlined in Image 1 and follows this description: An elderly man smiles at the camera. His face is wrinkled, his hair is messy in the wind, and he wears round-framed reading glasses. He has a worn-out red scarf with star patterns around his neck and is wearing a cotton-padded jacket.

Input image	Output image
	Make this bear sit under the moon (represented by a light gray crescent outline on a white background), holding a guitar, with small stars and speech bubbles with phrases such as "Be Kind" floating around.	Print this design on a T-shirt and a paper tote bag. A female model is displaying these items. The woman is also wearing a baseball cap with "Be kind" written on it.	A hyper-realistic 1/7 scale character model, designed as a commercial finished product, is placed on a desk with an iMac that has a white keyboard. The model stands on a clean, round, transparent acrylic base with no labels or text. Professional studio lighting highlights the sculpted details. On the iMac screen in the background, the ZBrush modeling process for the same model is displayed. Next to the model, place a packaging box with a transparent window on the front, showing only the clear plastic shell inside. The box is slightly taller than the model and reasonably sized to hold it.
	This bear is wearing an astronaut suit and pointing into the distance.	This bear is wearing a gorgeous ball gown, with its arms spread in an elegant dance pose.	This bear is wearing sportswear, holding a basketball, with one leg bent.

Input image	Output image
	Generate an image that matches the depth map outlined in Image 1 and follows this description: A blue bicycle is parked in a side alley, with a few weeds growing from cracks in the stone in the background.	Generate an image that matches the depth map outlined in Image 1 and follows this description: A worn-out red bicycle is parked on a muddy path, with a dense primeval forest in the background.

Input image	Output image
	Generate an image that matches the human pose outlined in Image 1 and follows this description: A Chinese woman in a Hanfu is holding an oil-paper umbrella in the rain, with a Suzhou garden in the background.	Generate an image that matches the human pose outlined in Image 1 and follows this description: A young man stands on a subway platform. He wears a baseball cap, a T-shirt, and jeans. A train is speeding by behind him.

Input image	Output image	Input image	Output image
	Replace 'HEALTH INSURANCE' on the Scrabble tiles with 'Tomorrow will be better'.		Change the phrase "Take a Breather" on the note to "Relax and Recharge".

Output image
Change "Qwen-Image" to a black ink-drip font.	Change "Qwen-Image" to a black handwriting font.	Change "Qwen-Image" to a black pixel font.
Change "Qwen-Image" to red.	Change "Qwen-Image" to a blue-purple gradient.	Change "Qwen-Image" to candy colors.
Change the material of "Qwen-Image" to metal.	Change the material of "Qwen-Image" to clouds.	Change the material of "Qwen-Image" to glass.

Input image	Output image	Input image	Output image
	Add a small wooden sign in front of the penguin that says "Welcome to Penguin Beach".		Remove the hair from the plate.

Input image	Output image	Input image	Output image
	Get a front view.		Face left.
	Get a rear view.		Face right.

Input image	Output image
	Restore the old photo, remove scratches, reduce noise, enhance details, high resolution, realistic image, natural skin tone, clear facial features, no distortion.
	Intelligently colorize the image based on its content to make it more vivid.

Input Image	Output Image
	Take a portrait of the boy from image 1 and the dog from image 2. The boy is hugging the dog, and both are very happy. Studio soft lighting, blue textured background.

Input Image	Output Image
	Please generate a set of four Polaroid photos with the theme "Seasonal Changes". Each photo is taken at the same location, under a tree in a park, but shows the scenes of spring, summer, autumn, and winter respectively. The person's attire should also match the season: a light jacket in spring, a short-sleeved shirt in summer, a trench coat in autumn, and a scarf and thick coat in winter. Place this set of photos on a dining table.

Input Image	Output Image
	Detect the laptop and alarm clock in the image, draw bounding boxes, and label them "laptop" and "clock".
	Segment the glass cup in the image.

Input Image	Output Image
	Extract the clothing items from the uploaded photo and arrange them in a flat-lay display on a pure white background. Maintain realistic details and material textures. Fashion e-commerce style, suitable for clothing display.

Input Image	Output Image
	Remove all watermarks from the image.
	Casually write "Time for Holiday?" on the sand with a hand.
	Change 18 to 29 and JUNE to SEPTEMBER.

Input Image	Output Image
	Keep the person's features unchanged and generate front, side, and back views.
	Reshoot this photo with a fisheye lens.

Input image 1	Input image 2	Output image
Image 1	Image 2	Prompt: Move Image 1 onto Image 2	Prompt: Move Image 2 onto Image 1

Task type	Trigger method	Usage notes
Text-to-video	Only pass `prompt`, do not pass `media`	Supports free setting of resolution, aspect ratio, and duration
Image-to-video	First frame to video	`type` set to `first\_frame`	`ratio` recommended as `adaptive`, model auto-matches first frame aspect ratio
First and last frame to video	`type` set to `first\_frame` and `last\_frame`	`ratio` recommended as `adaptive`, model auto-matches first frame aspect ratio
Multi-modal reference	Image reference	`type` set to `reference\_image`	Up to 10 images, each ≤20MB
Video reference	`type` set to `reference\_video`	Up to 5 clips, total duration ≤15 seconds, each file ≤100MB, frame rate ≥16 fps
Audio reference	`type` set to `reference\_audio`	Up to 5 clips, total duration ≤15 seconds, each file ≤15MB
Combined reference	`type` set to `reference\_image`/`reference\_video`/`reference\_audio` combination	Reference images/videos/audio, supports any combination of the three reference material types Image+Video Image+Audio Video+Audio Image+Video+Audio
File/Web page to video reference	`type` set to `file` or `link` (choose one, max 1 each), can be combined with `reference\_image`/`reference\_video`/`reference\_audio`	Parse document/web page content to generate video Documents and web links only support publicly accessible pages that do not require login
Video editing	`type` set to `reference\_video` (can be combined with `reference\_image`/`reference\_audio`) + prompt with editing intent (e.g., "edit video", "remove", "replace", "change to")	Add/remove/modify elements, style conversion, lighting editing, dialogue editing. `ratio` recommended as `adaptive`, `duration` recommended as `-1` (auto-preserves original video aspect ratio and duration)
Video extension	`type` set to `reference\_video` (can be combined with `reference\_image`/`reference\_audio`) + prompt with extension intent (e.g., "extend", "continue", "extend forward/backward")	Extend forward/backward/both directions. `ratio` recommended as `adaptive` (auto-preserves original video aspect ratio)

What is the author's main idea in this text?"}] ``` **Message array for subsequent requests** ```python messages = [{"role": "system","content": "You are a language teacher and you can help students with reading comprehension."}, {"role": "user","content": "

Please analyze the third paragraph of this text."}] ``` Although the questions differ, they reference the same article. Because the system prompt and article content remain unchanged, each request shares a large overlapping prefix, increasing the likelihood of a cache hit. 2. **Code auto-completion** In code auto-completion scenarios, the model auto-completes code based on the existing context. As the user continues coding, the prefix portion of the code remains unchanged. Context cache can cache the preceding code to improve completion speed. 3. **Multi-turn conversation** In a multi-turn conversation, the conversation history from all previous turns is included in the messages array. Each turn's request therefore shares the same prefix as the previous turn, resulting in a high probability of a cache hit. **Message array for the first turn of conversation** ```python messages=[{"role": "system","content": "You are a helpful assistant."}, {"role": "user","content": "Who are you?"}] ``` **Message array for the second turn of conversation** ```python messages=[{"role": "system","content": "You are a helpful assistant."}, {"role": "user","content": "Who are you?"}, {"role": "assistant","content": "I am Qwen, developed by Alibaba Cloud."}, {"role": "user","content": "What can you do?"}] ``` As the number of conversation turns increases, the benefits of caching -- faster inference and lower cost -- become more pronounced. 4. **Role playing or few-shot learning** In role playing or few-shot learning scenarios, you typically include a large amount of information in the prompt to guide the model's output format. This creates a large shared prefix across different requests. For example, if you want the model to act as a marketing expert, the system prompt contains a large amount of text information. The following are message examples for two requests: ```python system_prompt = """You are an experienced marketing expert. Please provide detailed marketing suggestions for different products in the following format: 1. Target audience: xxx 2. Main selling points: xxx 3. Marketing channels: xxx ... 12. Long-term development strategy: xxx Please ensure that your suggestions are specific, actionable, and highly relevant to the product features.""" # User message for the first request, asking about a smartwatch messages_1=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": "Please provide marketing suggestions for a newly launched smartwatch."} ] # User message for the second request, asking about a laptop. Because the system_prompt is the same, there is a high probability of hitting the Cache. messages_2=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": "Please provide marketing suggestions for a newly launched laptop."} ] ``` With context cache, the system can respond quickly once a cache hit occurs, even if the user frequently changes the type of product they are asking about, such as from a smartwatch to a laptop. 5. **Video understanding** In video understanding scenarios, if you ask multiple questions about the same video, placing the `video` before the `text` increases the probability of a cache hit. If you ask the same question about different videos, placing the `text` before the `video` increases the probability of a cache hit. The following is a message example for two requests for the same video: ````python # User message for the first request, asking about the content of this video messages1 = [ {"role":"system","content":[{"text": "You are a helpful assistant."}]}, {"role": "user", "content": [ {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250328/eepdcq/phase_change_480p.mov"}, {"text": "What is the content of this video?"} ] } ] # User message for the second request, asking about the video timestamp. Because the question is based on the same video, placing the video before the text has a high probability of hitting the Cache. messages2 = [ {"role":"system","content":[{"text": "You are a helpful assistant."}]}, {"role": "user", "content": [ {"video": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250328/eepdcq/phase_change_480p.mov"}, {"text": "Please describe the series of events in the video, and output the start time (start_time), end time (end_time), and event (event) in JSON format. Do not output the ```json``` code segment."} ] } ] ```` ## Session cache {#session-cache} In multi-turn conversation scenarios, enabling session cache allows the server to automatically cache conversation context, reducing inference latency and usage costs. You don't need to manage caching manually — just make calls as you would for a normal multi-turn conversation. ### Usage {#usage-2} Add the following field to the request header to control the session cache: - `x-dashscope-session-cache: enable`: Enables session cache. - `x-dashscope-session-cache: disable`: Disables session cache (default). ### Cache behavior {#cache-behavior} - **When session cache is enabled**: - If the model supports explicit cache: uses explicit cache. Billing and constraints follow [explicit cache](#explicit-cache). - If the model does not support explicit cache but supports implicit cache: uses implicit cache. Billing and constraints follow [implicit cache](#implicit-cache). - **When session cache is not enabled**: behaves the same as a normal call. Models that support implicit cache still have it enabled automatically, but do not benefit from session cache optimizations. ### Code examples {#code-examples} ```python Python import os from openai import OpenAI client = OpenAI( api_key=os.getenv("DASHSCOPE_API_KEY"), base_url="https://maas.qwencloudapi.com/compatible-mode/v1", # Enable session cache via default_headers default_headers={"x-dashscope-session-cache": "enable"} ) # Construct a long text exceeding 1024 tokens to ensure cache creation is triggered. # (If it does not reach 1024 tokens, cache creation will be triggered when the accumulated conversation context exceeds 1024 tokens.) long_context = "Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence." * 50 # First turn of conversation response1 = client.responses.create( model="qwen3.7-plus", input=long_context + "\n\nBased on the background knowledge above, please briefly introduce the random forest algorithm in machine learning.", ) print(f"First turn response: {response1.output_text}") # Second turn of conversation: Associate the context via previous_response_id. The cache is handled automatically by the server-side. response2 = client.responses.create( model="qwen3.7-plus", input="What are the main differences between it and GBDT?", extra_body={"previous_response_id": response1.id} ) print(f"Second turn response: {response2.output_text}") # Check the cache hit status usage = response2.usage print(f"Input tokens: {usage.input_tokens}") print(f"Cached hit tokens: {usage.prompt_tokens_details.cached_tokens}") ``` ```javascript Node.js import OpenAI from "openai"; const openai = new OpenAI({ apiKey: process.env.DASHSCOPE_API_KEY, baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1", // Enable session cache via defaultHeaders defaultHeaders: {"x-dashscope-session-cache": "enable"} }); // Construct a long text exceeding 1024 tokens to ensure cache creation is triggered. // (If it does not reach 1024 tokens, cache creation will be triggered when the accumulated conversation context exceeds 1024 tokens.) const longContext = "Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence.".repeat(50); async function main() { // First turn of conversation const response1 = await openai.responses.create({ model: "qwen3.7-plus", input: longContext + "\n\nBased on the background knowledge above, please briefly introduce the random forest algorithm in machine learning, including its basic principles and application scenarios." }); console.log(`First turn response: ${response1.output_text}`); // Second turn of conversation: Associate the context via previous_response_id. The cache is handled automatically by the server-side. const response2 = await openai.responses.create({ model: "qwen3.7-plus", input: "What are the main differences between it and GBDT?", extra_body: { previous_response_id: response1.id } }); console.log(`Second turn response: ${response2.output_text}`); // Check the cache hit status console.log(`Input tokens: ${response2.usage.input_tokens}`); console.log(`Cached hit tokens: ${response2.usage.prompt_tokens_details.cached_tokens}`); } main(); ``` ```bash curl # First turn of conversation # Please replace the input with a long text exceeding 1024 tokens to ensure cache creation is triggered. curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/responses \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H "Content-Type: application/json" \ -H "x-dashscope-session-cache: enable" \ -d '{ "model": "qwen3.7-plus", "input": "Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence. Artificial intelligence is an important branch of computer science, dedicated to the research and development of theories, methods, technologies, and application systems that can simulate, extend, and expand human intelligence.\n\nBased on the background knowledge above, please briefly introduce the random forest algorithm in machine learning, including its basic principles and application scenarios." }' # Second turn of conversation - Use the id returned from the previous turn as previous_response_id curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/responses \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H "Content-Type: application/json" \ -H "x-dashscope-session-cache: enable" \ -d '{ "model": "qwen3.7-plus", "input": "What are the main differences between it and GBDT?", "previous_response_id": "response_id_from_the_first_turn" }' ``` **Second-turn response example (cache hit)** The `cached_tokens` field shows the number of hit cache tokens: ```json { "id": "145584fd-3dce-4890-99dc-e3896d7f5a42", "created_at": 1772440976.0, "error": null, "incomplete_details": null, "instructions": null, "metadata": null, "model": "qwen3.7-plus", "object": "response", "output": [ { "id": "msg_62a4e323-d78c-46c7-8469-2ad50f8af4b1", "type": "reasoning", "content": null }, { "id": "msg_560e34a6-1bdf-42ae-993e-590b38249146", "content": [ { "annotations": [], "text": "Although both Random Forest and GBDT (Gradient Boosting Decision Tree) are ensemble algorithms based on decision trees, they have the following main differences:\n\n1. **Different Ensemble Strategies**\n * **Random Forest**: Based on the **Bagging** idea. Each tree is trained independently, with no dependency between them.\n * **GBDT**: Based on the **Boosting** idea. The trees have a strong dependency relationship, where the next tree aims to fit the residuals (negative gradient) of the previous tree's prediction.\n\n2. **Different Training Methods**\n * **Random Forest**: Supports **parallel training** because the trees are independent, which usually results in higher computational efficiency.\n * **GBDT**: Must be **trained serially** because the next tree depends on the output of the previous one, making it inherently difficult to parallelize (although engineering implementations like XGBoost have made parallel optimizations at the feature level).\n\n3. **Different Optimization Objectives**\n * **Random Forest**: Mainly reduces **variance** by averaging multiple models to prevent overfitting and improve stability.\n * **GBDT**: Mainly reduces **bias** by progressively correcting errors to improve the model's fitting ability and accuracy.\n\n4. **Sensitivity to Outliers**\n * **Random Forest**: Relatively robust and not sensitive to outliers.\n * **GBDT**: More sensitive to outliers because outliers produce large residuals, which affect the fitting direction of subsequent trees.\n\nIn summary, Random Forest excels in stability and parallel efficiency, while GBDT usually performs better in terms of accuracy but is more complex to tune and slower to train.", "type": "output_text" } ], "role": "assistant", "status": "completed", "type": "message" } ], "parallel_tool_calls": false, "temperature": null, "tool_choice": "auto", "tools": [], "top_p": null, "status": "completed", "usage": { "input_tokens": 1524, "input_tokens_details": { "cached_tokens": 1305 }, "output_tokens": 1534, "output_tokens_details": { "reasoning_tokens": 1187 }, "total_tokens": 3058 } } ``` The `input_tokens` for the second turn of the conversation is 1524, of which the `cached_tokens` is 1305. This indicates that the context from the first turn was a cache hit, which can effectively reduce inference latency and cost. ### Billing {#billing-3} Session cache billing depends on the actual cache type used: - When explicit cache is used, billing follows [explicit cache](#explicit-cache) rules. - When implicit cache is used, billing follows [implicit cache](#implicit-cache) rules. The number of hit cache tokens can be viewed in the `usage.input_tokens_details.cached_tokens` parameter. ### Limitations {#limitations} - The minimum cacheable prompt length is **1024** tokens. - The cache validity period is **5 minutes** and is reset upon a hit. - It is applicable only to the Responses API and must be used with the `previous_response_id` parameter for multi-turn conversations. ## FAQ {#faq} ### How long is the context cache retained (validity period)? {#how-long-is-the-context-cache-retained-validity-period} The validity period of the context cache depends on the cache type: - **Explicit cache**: The validity period is 5 minutes, and each cache hit resets it to another 5 minutes. If the cache block is not hit within 5 minutes, the system automatically clears it. - **Implicit cache**: Managed automatically by the system with no fixed validity period. The system periodically clears cache data that has not been used for a long time. This validity period refers to the lifecycle of the context cache during API calls. It is not the same feature as the conversation history shown in the console's Model Experience or Model Debugging pages. ### How do I disable implicit cache? {#how-do-i-disable-implicit-cache} You cannot disable it. Implicit cache is automatically enabled for all supported models because it does not affect response quality and reduces costs while improving response speed when the cache is hit. ### Why was the explicit cache not hit after I created it? {#why-was-the-explicit-cache-not-hit-after-i-created-it} There are several possible reasons: - The cache was not hit within 5 minutes of creation, and the system cleared the cache block after it expired. - If the last `content` block is separated from the existing cache block by more than 20 `content` blocks, the cache is not hit. We recommend that you create a new cache block. ### Does hitting the explicit cache reset its validity? {#does-hitting-the-explicit-cache-reset-its-validity} Yes. Each hit resets the validity period of that cache block to 5 minutes. ### Is the explicit cache shared between different accounts? {#is-the-explicit-cache-shared-between-different-accounts} No. Both implicit and explicit cache data are isolated at the account level and are not shared across accounts. ### Is explicit cache shared between different models? {#is-explicit-cache-shared-between-different-models} No. Cache data is isolated between models and is not shared. ### Why doesn't `input_tokens` equal `cache_creation_input_tokens` + `cached_tokens`? {#why-doesnt-input-tokens-equal-cache-creation-input-tokens-cached-tokens} To ensure model output quality, the backend service appends a small number of tokens (usually fewer than 10) after the user-provided prompt. These tokens are placed after the `cache_control` marker, so they are not counted for cache creation or hits. However, they are included in the total `input_tokens`. # Streaming output Source: https://docs.qwencloud.com/developer-guides/run-and-scale/streaming > Receive text output token by token as it is generated. ## Enable streaming {#enable-streaming} No usage by default. Set `stream_options` to get token counts in the **last chunk only**. ```python Python {7,8} import os from openai import OpenAI client = OpenAI(api_key=os.getenv("DASHSCOPE_API_KEY"), base_url="https://maas.qwencloudapi.com/compatible-mode/v1") completion = client.chat.completions.create( model="qwen3.7-plus", messages=[{"role": "user", "content": "Hi"}], stream=True, # ← enable streaming stream_options={"include_usage": True}, # ← usage in last chunk only ) for chunk in completion: if chunk.choices: print(chunk.choices[0].delta.content or "", end="", flush=True) elif chunk.usage: # ← last chunk: usage only print(f"\nTokens: {chunk.usage.total_tokens}") ``` ```javascript Node.js {7,8} import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.DASHSCOPE_API_KEY, baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1" }); const stream = await client.chat.completions.create({ model: "qwen3.7-plus", messages: [{ role: "user", content: "Hi" }], stream: true, // ← enable streaming stream_options: { include_usage: true }, // ← usage in last chunk }); for await (const chunk of stream) { if (chunk.choices?.length > 0) process.stdout.write(chunk.choices[0]?.delta?.content || ""); else if (chunk.usage) console.log(`\nTokens: ${chunk.usage.total_tokens}`); } ``` ```bash curl curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/chat/completions \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H "Content-Type: application/json" --no-buffer \ -d '{"model":"qwen3.7-plus","messages":[{"role":"user","content":"Hi"}],"stream":true,"stream_options":{"include_usage":true}}' ``` ```python Python {6} import os from openai import OpenAI client = OpenAI(api_key=os.getenv("DASHSCOPE_API_KEY"), base_url="https://maas.qwencloudapi.com/compatible-mode/v1") stream = client.responses.create( model="qwen3.7-plus", input="Hi", stream=True, # ← enable streaming ) for event in stream: if event.type == "response.output_text.delta": print(event.delta, end="", flush=True) elif event.type == "response.completed": print(f"\nTokens: {event.response.usage.total_tokens}") ``` ```javascript Node.js {6} import OpenAI from "openai"; const client = new OpenAI({ apiKey: process.env.DASHSCOPE_API_KEY, baseURL: "https://maas.qwencloudapi.com/compatible-mode/v1" }); const stream = await client.responses.create({ model: "qwen3.7-plus", input: "Hi", stream: true, // ← enable streaming }); for await (const event of stream) { if (event.type === "response.output_text.delta") process.stdout.write(event.delta); else if (event.type === "response.completed") console.log(`\nTokens: ${event.response.usage.total_tokens}`); } ``` ```bash curl curl -X POST https://maas.qwencloudapi.com/compatible-mode/v1/responses \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H "Content-Type: application/json" --no-buffer \ -d '{"model":"qwen3.7-plus","input":"Hi","stream":true}' ``` Unlike OpenAI compatible (last chunk only), DashScope returns real-time token usage in **every chunk** — useful for monitoring costs or stopping early. Qwen3.5 and Qwen3.6 models use the `multimodal-generation` endpoint shown below. Earlier models such as qwen-plus and qwen3-max use the `text-generation` endpoint instead. See [DashScope API reference](/api-reference/chat/dashscope) for details. ```python Python {10,11} from http import HTTPStatus import dashscope dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1' from dashscope import MultiModalConversation responses = MultiModalConversation.call( model="qwen3.7-plus", messages=[{"role": "user", "content": [{"text": "Hi"}]}], stream=True, # ← enable streaming incremental_output=True, # ← recommended: new tokens only per chunk ) for resp in responses: if resp.status_code == HTTPStatus.OK: content = resp.output.choices[0].message.content if content: print(content[0]["text"], end="", flush=True) ``` ```java Java {12,14} import java.util.*; import com.alibaba.dashscope.aigc.multimodalconversation.*; import com.alibaba.dashscope.common.Role; import com.alibaba.dashscope.utils.Constants; Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1"; MultiModalConversationParam param = MultiModalConversationParam.builder() .apiKey(apiKey).model("qwen3.7-plus") .messages(Arrays.asList( MultiModalConversationMessage.builder().role(Role.USER.getValue()) .content(Arrays.asList(Collections.singletonMap("text", "Hi"))).build())) .incrementalOutput(true) // ← recommended: new tokens only .build(); new MultiModalConversation().streamCall(param) // ← streamCall, not call .subscribe(msg -> System.out.print( msg.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text"))); ``` ```bash curl curl -X POST https://maas.qwencloudapi.com/api/v1/services/aigc/multimodal-generation/generation \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" -H "Content-Type: application/json" \ -H "X-DashScope-SSE: enable" \ -d '{"model":"qwen3.7-plus","input":{"messages":[{"role":"user","content":[{"text":"Hi"}]}]},"parameters":{"incremental_output":true}}' ``` ## Event format {#event-format} Each SSE event is a `data:` line containing a JSON chunk. The final `data: [DONE]` signals the end of the stream. ```text data: {"choices":[{"delta":{"content":"I am"},...,"finish_reason":null}],...} data: {"choices":[{"delta":{"content":" Qwen"},...,"finish_reason":null}],...} data: {"choices":[{"delta":{"content":""},...,"finish_reason":"stop"}],...} data: [DONE] ``` ## Streaming with thinking mode {#streaming-with-thinking-mode} Two-phase streaming: thinking first, then the answer. ```python for chunk in completion: delta = chunk.choices[0].delta if hasattr(delta, "reasoning_content") and delta.reasoning_content: print(delta.reasoning_content, end="", flush=True) # ← phase 1: thinking if hasattr(delta, "content") and delta.content: print(delta.content, end="", flush=True) # ← phase 2: answer ``` ```python for event in stream: if event.type == "response.reasoning_text.delta": print(event.delta, end="", flush=True) # ← phase 1: thinking elif event.type == "response.output_text.delta": print(event.delta, end="", flush=True) # ← phase 2: answer ``` ```python for chunk in completion: msg = chunk.output.choices[0].message if msg.reasoning_content: # ← phase 1: thinking print(msg.reasoning_content, end="", flush=True) if msg.content: # ← phase 2: answer print(msg.content, end="", flush=True) ``` → Full config: [Reasoning](/developer-guides/text-generation/thinking) | Qwen3-Omni: [Audio and video](/developer-guides/speech/multimodal-speech) ## Streaming with tool calls {#streaming-with-tool-calls} When streaming [function calling](/developer-guides/tool-calling/function-calling) responses, tool call arguments arrive as incremental deltas that must be concatenated before JSON parsing. Each chunk's `delta` may contain `tool_calls[i].function.arguments` — a partial JSON string. Accumulate all fragments per tool call index, then `JSON.parse()` the complete string. ```python tool_args = {} for chunk in completion: delta = chunk.choices[0].delta if delta.tool_calls: for tc in delta.tool_calls: tool_args.setdefault(tc.index, "") tool_args[tc.index] += tc.function.arguments or "" # After stream ends: for idx, args_str in tool_args.items(): parsed = json.loads(args_str) ``` Tool calls emit `response.function_call_arguments.delta` events. Concatenate deltas until `response.function_call_arguments.done`. ```python args_buffer = "" for event in stream: if event.type == "response.function_call_arguments.delta": args_buffer += event.delta elif event.type == "response.function_call_arguments.done": parsed = json.loads(args_buffer) args_buffer = "" ``` With [thinking mode](/developer-guides/text-generation/thinking) enabled, the stream delivers three phases: thinking tokens, then tool call deltas, then (after you send tool results) the final answer. ## Notes {#notes} - **Nginx proxy**: set `proxy_buffering off` or SSE events will buffer - **High concurrency**: size connection pool, monitor file descriptors - **Web frontend**: use `ReadableStream` + `TextDecoderStream` - **Quality**: streaming does not affect response quality - **Streaming-only models**: QwQ and QVQ only support streaming output. Non-streaming calls to these models will fail or return empty content. ## FAQ {#faq} **What is the difference between streaming and non-streaming calls?** - **Timeout**: Non-streaming calls have a maximum timeout of at least 300 seconds; the actual duration varies by deployment region and model. - **Output structure**: Non-streaming calls return the complete response as a single JSON object. Streaming calls return data chunks incrementally via the SSE protocol, where each chunk contains partial generated content that the client must concatenate. - **Feature compatibility**: Both support JSON Mode, Function Call, and other features with no functional differences. We recommend using streaming output to avoid timeout issues and provide a better user experience. **Does streaming output support JSON Mode (structured output)?** Yes. Set `stream` to `true` and `response_format` to `{"type": "json_object"}` in the same request. The model will return JSON content incrementally via streaming. The concatenated complete output will be valid JSON. # Async task management Source: https://docs.qwencloud.com/developer-guides/run-and-scale/async-task-management > Two async patterns on QwenCloud: task-based for media generation, batch for high-volume text processing QwenCloud offers two async processing systems. Choose based on what you're building: | | Task API | Batch API | | -------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------ | | **Use case** | Image generation, video generation, file transcription | High-volume text generation, embeddings | | **How it works** | Submit one request → get a task ID → poll for result | Upload a JSONL file of requests → poll for completion → download results | | **Endpoint** | `maas.qwencloudapi.com/api/v1/tasks/` | `maas.qwencloudapi.com/compatible-mode/v1/batches` | | **Cost** | Standard pricing | **50% discount** | | **Completion time** | Seconds to minutes | Up to 24h (configurable to 336h) | | **Result retention** | 24 hours | 30 days | | **Max per request** | 1 task (with optional multi-output like `n=4`) | 50,000 requests per file, 500 MB | ## Task API {#task-api} Image generation, video generation, and file transcription use the Task API: you submit a single request, receive a task ID, and poll for the result. ### How it works {#how-it-works} Every task follows the same two-step pattern: 1. **Create a task** — Send a POST request and receive a `task_id` 2. **Query the result** — Poll `GET /api/v1/tasks/{task_id}` until the task reaches a terminal state ``` POST (create) ──→ task_id │ ┌─────────────┘ ▼ ┌─────────┐ ┌─────────┐ ┌───────────┐ │ PENDING │───→│ RUNNING │───→│ SUCCEEDED │ └─────────┘ └─────────┘ └───────────┘ │ │ ▼ ▼ ┌──────────┐ ┌────────┐ │ CANCELED │ │ FAILED │ └──────────┘ └────────┘ ``` #### Task states {#task-states} | State | Meaning | | ----------- | --------------------------------------------- | | `PENDING` | Queued, waiting to start | | `RUNNING` | Actively processing | | `SUCCEEDED` | Completed successfully | | `FAILED` | Encountered an error | | `CANCELED` | Manually canceled (only from `PENDING` state) | | `UNKNOWN` | Task ID expired or cannot be queried | ### Create a task {#create-a-task} Some APIs (like image generation) support both synchronous and asynchronous modes. Add the `X-DashScope-Async` header to force async execution: ```bash curl -X POST https://maas.qwencloudapi.com/api/v1/services/aigc/image-generation/generation \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" \ -H "Content-Type: application/json" \ -H "X-DashScope-Async: enable" \ -d '{ "model": "wan2.6-t2i", "input": { "messages": [ { "role": "user", "content": [ {"text": "A cat sitting on a windowsill at sunset"} ] } ] } }' ``` The response returns a `task_id`: ```json { "request_id": "e5d5af82-9a08-xxx", "output": { "task_id": "86ecf553-d340-xxx", "task_status": "PENDING" } } ``` Video generation APIs are always asynchronous — you do not need the `X-DashScope-Async` header for these. ### Query the result {#query-the-result} Poll the task endpoint with the returned `task_id`: ```bash curl -X GET "https://maas.qwencloudapi.com/api/v1/tasks/86ecf553-d340-xxx" \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" ``` ```python import requests import os task_id = "86ecf553-d340-xxx" url = f"https://maas.qwencloudapi.com/api/v1/tasks/{task_id}" headers = {"Authorization": f"Bearer {os.getenv('DASHSCOPE_API_KEY')}"} response = requests.get(url, headers=headers) result = response.json() print(result["output"]["task_status"]) ``` A completed task returns the result in the `output` field: ```json { "request_id": "e5d5af82-9a08-xxx", "output": { "task_id": "86ecf553-d340-xxx", "task_status": "SUCCEEDED", "submit_time": "2025-01-15 10:30:00.000", "scheduled_time": "2025-01-15 10:30:01.000", "end_time": "2025-01-15 10:30:12.000", "finished": true, "choices": [ { "finish_reason": "stop", "message": { "role": "assistant", "content": [ { "image": "https://dashscope-result-xxx.oss-xxx.aliyuncs.com/...", "type": "image" } ] } } ] }, "usage": { "image_count": 1, "input_tokens": 0, "output_tokens": 0 } } ``` Older models (Wan 2.5 and earlier) return a different response structure with `results` and `task_metrics` fields instead of `choices`. See the [text-to-image API reference](/api-reference/image-generation/wan-text-to-image-v2/query-result) for details on both formats. A failed task includes an error code and message: ```json { "output": { "task_id": "86ecf553-d340-xxx", "task_status": "FAILED", "code": "DataInspectionFailed", "message": "Input or output data may contain inappropriate content." } } ``` ### Polling strategies {#polling-strategies} Naive fixed-interval polling wastes API calls and may hit rate limits. Use exponential backoff instead. Start with a short interval and increase gradually. Different modalities have different typical completion times: | Modality | Initial interval | Increase factor | Timeout | | ------------------------ | ---------------- | --------------- | ------------------------ | | Image generation | 3 seconds | 1.5× | 2 minutes | | Video generation | 15 seconds | 1.5× | 5 minutes | | File transcription (ASR) | 5 seconds | 1.5× | Varies with audio length | ```python import time import requests import os def poll_task(task_id, initial_interval=3, max_interval=15, timeout=120): """Poll a task with exponential backoff.""" url = f"https://maas.qwencloudapi.com/api/v1/tasks/{task_id}" headers = {"Authorization": f"Bearer {os.getenv('DASHSCOPE_API_KEY')}"} interval = initial_interval elapsed = 0 while elapsed < timeout: response = requests.get(url, headers=headers) result = response.json() status = result["output"]["task_status"] if status == "SUCCEEDED": return result elif status == "FAILED": raise Exception( f"Task failed: {result['output'].get('code', 'Unknown')} - " f"{result['output'].get('message', '')}" ) time.sleep(interval) elapsed += interval interval = min(interval * 1.5, max_interval) raise TimeoutError(f"Task {task_id} did not complete within {timeout}s") # Image generation: poll every 3s, escalate to 15s, timeout at 2min result = poll_task("86ecf553-d340-xxx", initial_interval=3, max_interval=15, timeout=120) # Video generation: poll every 15s, escalate to 60s, timeout at 5min result = poll_task("86ecf553-d340-xxx", initial_interval=15, max_interval=60, timeout=300) ``` ```javascript async function pollTask(taskId, { initialInterval = 3000, maxInterval = 15000, timeout = 120000 } = {}) { const url = `https://maas.qwencloudapi.com/api/v1/tasks/${taskId}`; const headers = { Authorization: `Bearer ${process.env.DASHSCOPE_API_KEY}` }; let interval = initialInterval; const deadline = Date.now() + timeout; while (Date.now() < deadline) { const res = await fetch(url, { headers }); const result = await res.json(); const { task_status, code, message } = result.output; if (task_status === "SUCCEEDED") return result; if (task_status === "FAILED") throw new Error(`Task failed: ${code} - ${message}`); await new Promise(resolve => setTimeout(resolve, interval)); interval = Math.min(interval * 1.5, maxInterval); } throw new Error(`Task ${taskId} did not complete within ${timeout}ms`); } ``` ### SDK-level abstraction {#sdk-level-abstraction} The DashScope Python SDK encapsulates the polling loop. Use `call()` for a synchronous experience, or `async_call()` + `wait()` for explicit control. ```python import dashscope from dashscope.aigc.image_generation import ImageGeneration dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1' message = {"role": "user", "content": [{"text": "A cat sitting on a windowsill at sunset"}]} # Option 1: Synchronous — SDK polls internally result = ImageGeneration.call( model="wan2.7-image-pro", messages=[message], n=1 ) print(result.output.choices[0].message.content[0]["image"]) # Option 2: Explicit async — you control when to wait task = ImageGeneration.async_call( model="wan2.7-image-pro", messages=[message], n=1 ) # Do other work here... result = ImageGeneration.wait(task) print(result.output.choices[0].message.content[0]["image"]) ``` The same pattern applies across modalities: ```python from dashscope import VideoSynthesis task = VideoSynthesis.async_call(model="wan2.6-t2v", prompt="...") result = VideoSynthesis.wait(task) ``` ### Manage tasks at scale {#manage-tasks-at-scale} #### List tasks {#list-tasks} Query tasks by time range, status, or model: ```bash curl -X GET "https://maas.qwencloudapi.com/api/v1/tasks/?start_time=20250115100000&end_time=20250115120000&status=FAILED&model_name=wan2.6-t2i&page_no=1&page_size=20" \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" ``` Supported filters: | Parameter | Description | | ------------ | ------------------------------------------------------------------- | | `start_time` | Start of time range, format: `YYYYMMDDhhmmss` | | `end_time` | End of time range, format: `YYYYMMDDhhmmss` | | `status` | Filter by task status (`PENDING`, `RUNNING`, `SUCCEEDED`, `FAILED`) | | `model_name` | Filter by model name | | `api_key_id` | Filter by API key ID | | `page_no` | Page number (starting from 1) | | `page_size` | Results per page | The time range cannot exceed 24 hours. If both `start_time` and `end_time` are omitted, the API returns tasks from the last 24 hours. #### Cancel a task {#cancel-a-task} Cancel a task that is still in `PENDING` state: ```bash curl -X POST "https://maas.qwencloudapi.com/api/v1/tasks/86ecf553-d340-xxx/cancel" \ -H "Authorization: Bearer $DASHSCOPE_API_KEY" ``` Only tasks in `PENDING` state can be canceled. Once a task moves to `RUNNING`, it will continue to completion. #### Rate limits {#rate-limits} Task management endpoints (query, list, cancel) share a rate limit of **20 QPS per account**. If you manage many concurrent tasks, batch your status checks rather than polling each task individually at high frequency. ### Task API best practices {#task-api-best-practices} **Download results immediately** — Task data and result URLs (images, videos) are retained for **24 hours** only. After that, both the task metadata and generated files are automatically deleted. Always download and save results to persistent storage as soon as the task succeeds. **Handle multi-output tasks** — When you request multiple outputs (such as `n=4` images), the task is marked `SUCCEEDED` if **at least one** output is generated. Iterate over the `choices` array and check `finish_reason` to handle partial success: ```python result = poll_task(task_id) choices = result["output"]["choices"] print(f"{len(choices)} outputs generated") for choice in choices: if choice["finish_reason"] == "stop": for item in choice["message"]["content"]: if "image" in item: download(item["image"]) else: print(f"Output skipped: {choice['finish_reason']}") ``` **Avoid duplicate tasks** — Each POST request creates a new task, even with identical parameters. If your application retries a failed submission, track task IDs to avoid duplicate work and unnecessary cost. ## Batch API {#batch-api} The Batch API processes large volumes of text generation or embedding requests at **50% of the standard price**. You upload a JSONL file of requests, wait for processing to complete, and download the results. | Feature | Details | | --------------------- | ---------------------------------------------------------- | | **Supported models** | Qwen text generation models, text embedding models | | **Input format** | JSONL file, up to 50,000 requests / 500 MB | | **Completion window** | 24 hours (configurable up to 336 hours) | | **Result retention** | 30 days | | **Cancellation** | Supported at any stage (in-progress requests finish first) | The Batch API uses the OpenAI-compatible endpoint and SDK. For the complete guide with examples, input format, task states, and management operations, see [Batch API](/developer-guides/text-generation/batch). ## Common errors {#common-errors} These errors apply to both the Task API and the Batch API: | Error | Cause | Action | | ---------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------ | | `DataInspectionFailed` | Input or output blocked by content moderation | Modify the prompt and retry. See [Safety](/developer-guides/run-and-scale/safety) | | `Throttling.RateQuota` | Rate limit exceeded | Reduce request frequency; increase polling interval | | Task/batch stuck | Processing taking longer than expected | For tasks: continue polling until timeout. For batches: increase `completion_window` | ## Next steps {#next-steps} - [Manage asynchronous tasks](/api-reference/more/manage-asynchronous-tasks) — Task API reference (query, list, cancel) - [Batch API](/developer-guides/text-generation/batch) — Full Batch API guide with all languages - [Text-to-image](/developer-guides/image-generation/text-to-image) — Image generation with async task examples - [Text-to-video](/developer-guides/video-generation/text-to-video) — Video generation with async task examples - [Rate limits](/developer-guides/administration/rate-limits) — Account-level rate limit details # Connection reuse and pooling Source: https://docs.qwencloud.com/developer-guides/run-and-scale/connection-pooling > HTTP connection reuse and WebSocket connection pooling for high-concurrency workloads. Reusing connections reduces resource consumption and improves throughput. The strategy depends on the protocol: - **HTTP APIs** (text generation, multimodal, embeddings): reuse TCP connections via connection pool configuration (Java) or Session objects (Python). - **WebSocket APIs** (TTS, real-time speech): pool synthesizer objects that hold long-lived WebSocket connections. ## Prerequisites {#prerequisites} - Obtain and configure your API Key as the `DASHSCOPE_API_KEY` environment variable. - Install the latest DashScope SDK: - **Python SDK**: >= 1.25.2 - **Java SDK**: >= 2.16.6 ## HTTP connection reuse {#http-connection-reuse} The DashScope endpoint differs by model type: - **Text models** (`qwen-plus`, `qwen3-max`, etc.): use the `Generation` class, which routes to `/services/aigc/text-generation/generation`. - **Multimodal models** (`qwen3.7-plus`, `qwen3-vl-plus`, etc.): use the `MultiModalConversation` class, which routes to `/services/aigc/multimodal-generation/generation`. ### Java SDK {#java-sdk} Connection pooling is enabled by default. Adjust the following parameters as needed. | Parameter | Description | Default | Unit | Notes | | ----------------------------- | ----------------------------------------------------------------------------- | ------- | -------- | ------------------------------------------------------------------------- | | `connectTimeout` | Timeout for establishing a connection. | 120 | seconds | Shorter timeouts reduce wait time in low-latency scenarios. | | `readTimeout` | Timeout for reading data. | 300 | seconds | | | `writeTimeout` | Timeout for writing data. | 60 | seconds | | | `connectionIdleTimeout` | Timeout for idle connections. | 300 | seconds | Longer idle timeouts avoid frequent reconnections under high concurrency. | | `connectionPoolSize` | Maximum connections in the pool. | 32 | items | Too few connections cause blocking; too many increase server load. | | `maximumAsyncRequests` | Maximum concurrent requests across all hosts. Must be ≤ `connectionPoolSize`. | 32 | requests | | | `maximumAsyncRequestsPerHost` | Maximum concurrent requests per host. Must be ≤ `maximumAsyncRequests`. | 32 | items | | Configure connection pool parameters and call a model service: ```java // Recommended DashScope SDK version >= 2.12.0 import java.time.Duration; import java.util.Arrays; import java.util.Collections; import java.util.HashMap; import java.util.Map; import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation; import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam; import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult; import com.alibaba.dashscope.common.MultiModalMessage; import com.alibaba.dashscope.common.Role; import com.alibaba.dashscope.exception.ApiException; import com.alibaba.dashscope.exception.InputRequiredException; import com.alibaba.dashscope.exception.NoApiKeyException; import com.alibaba.dashscope.protocol.ConnectionConfigurations; import com.alibaba.dashscope.protocol.Protocol; import com.alibaba.dashscope.utils.Constants; public class Main { public static MultiModalConversationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException { MultiModalConversation conv = new MultiModalConversation(Protocol.HTTP.getValue(), "https://maas.qwencloudapi.com/api/v1"); Map textContent = new HashMap<>(); textContent.put("text", "Who are you?"); MultiModalMessage userMsg = MultiModalMessage.builder() .role(Role.USER.getValue()) .content(Collections.singletonList(textContent)) .build(); MultiModalConversationParam param = MultiModalConversationParam.builder() // If you have not configured the environment variable, replace with your API key: .apiKey("sk-xxx") .apiKey(System.getenv("DASHSCOPE_API_KEY")) .model("qwen3.7-plus") .messages(Collections.singletonList(userMsg)) .build(); return conv.call(param); } public static void main(String[] args) { // Connection pool configuration Constants.connectionConfigurations = ConnectionConfigurations.builder() .connectTimeout(Duration.ofSeconds(10)) // Timeout for establishing a connection, default 120s .readTimeout(Duration.ofSeconds(300)) // Timeout for reading data, default 300s .writeTimeout(Duration.ofSeconds(60)) // Timeout for writing data, default 60s .connectionIdleTimeout(Duration.ofSeconds(300)) // Timeout for idle connections, default 300s .connectionPoolSize(256) // Maximum connections in the connection pool, default 32 .maximumAsyncRequests(256) // Maximum concurrent requests, default 32 .maximumAsyncRequestsPerHost(256) // Maximum concurrent requests per host, default 32 .build(); try { MultiModalConversationResult result = callWithMessage(); System.out.println(result.getOutput().getChoices().get(0).getMessage().getContent().get(0).get("text")); } catch (ApiException | NoApiKeyException | InputRequiredException e) { System.err.println("An error occurred while calling the service: " + e.getMessage()); } System.exit(0); } } ``` ### Python SDK {#python-sdk} The Python SDK supports connection reuse via a custom Session. Two methods are available: [async (aiohttp)](#async-aiohttp) and [sync (requests.Session)](#sync-requests-session). #### Async (aiohttp) {#async-aiohttp} Use `aiohttp.ClientSession` with `aiohttp.TCPConnector` for async connection reuse. | Parameter | Description | Default | Notes | | ---------------- | ------------------------- | ------------- | ------------------------------------------------- | | `limit` | Total connection limit | 100 | Higher values improve concurrency. | | `limit_per_host` | Connection limit per host | 0 (unlimited) | Prevents excessive load on a single host. | | `ssl` | SSL context configuration | None | SSL certificate validation for HTTPS connections. | ```python import asyncio import aiohttp import ssl import certifi from dashscope import AioMultiModalConversation import dashscope import os async def main(): dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1' # If you have not configured the environment variable, replace with your API key: dashscope.api_key = "sk-xxx" dashscope.api_key = os.getenv("DASHSCOPE_API_KEY") # Configure connection parameters connector = aiohttp.TCPConnector( limit=100, # Total connection limit limit_per_host=30, # Connection limit per host ssl=ssl.create_default_context(cafile=certifi.where()), ) # Create a custom Session and pass it to the call method async with aiohttp.ClientSession(connector=connector) as session: response = await AioMultiModalConversation.call( model='qwen3.7-plus', messages=[{'role': 'user', 'content': [{'text': 'Hello, please introduce yourself'}]}], session=session, # Pass the custom Session ) print(response) asyncio.run(main()) ``` #### Sync (requests.Session) {#sync-requests-session} Use `requests.Session` for sync connection reuse. Requests within the same Session reuse the TCP connection. ```python import requests from dashscope import MultiModalConversation import dashscope import os dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1' # If you have not configured the environment variable, replace with your API key: dashscope.api_key = "sk-xxx" dashscope.api_key = os.getenv("DASHSCOPE_API_KEY") # Use a with statement to ensure the Session closes correctly with requests.Session() as session: response = MultiModalConversation.call( model='qwen3.7-plus', messages=[{'role': 'user', 'content': [{'text': 'Hello'}]}], session=session # Pass the custom Session ) print(response) ``` Reuse the same Session across multiple calls: ```python import requests from dashscope import MultiModalConversation import dashscope import os dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1' # If you have not configured the environment variable, replace with your API key: dashscope.api_key = "sk-xxx" dashscope.api_key = os.getenv("DASHSCOPE_API_KEY") # Create a Session object session = requests.Session() try: # Reuse the same Session for multiple calls response1 = MultiModalConversation.call( model='qwen3.7-plus', messages=[{'role': 'user', 'content': [{'text': 'Hello'}]}], session=session ) print(response1) response2 = MultiModalConversation.call( model='qwen3.7-plus', messages=[{'role': 'user', 'content': [{'text': 'Introduce yourself'}]}], session=session ) print(response2) finally: # Ensure the Session closes correctly session.close() ``` ## WebSocket connection pooling {#websocket-connection-pooling} TTS services use WebSocket connections for real-time streaming. In production, creating a new connection per request wastes resources and adds latency. This section covers connection pooling, object pooling, and concurrent request management for high-throughput TTS workloads. ### Python: Object pool {#python-object-pool} The Python SDK provides `SpeechSynthesizerObjectPool` to manage and reuse `SpeechSynthesizer` instances. The pool pre-creates objects and establishes WebSocket connections at initialization, eliminating per-request connection overhead. **Pool sizing**: Set `max_size` to 1.5x-2x your peak concurrency. Do not exceed your account's QPS limit. ```python import os import threading import dashscope from dashscope.audio.tts_v2 import * dashscope.api_key = os.getenv("DASHSCOPE_API_KEY") dashscope.base_websocket_api_url = 'wss://maas.qwencloudapi.com/api-ws/v1/inference' # Create a global object pool (one-time cost at startup) pool = SpeechSynthesizerObjectPool(max_size=20) def synthesize(text, task_id): complete_event = threading.Event() class Callback(ResultCallback): def on_open(self): self.file = open(f'result_{task_id}.mp3', 'wb') def on_complete(self): complete_event.set() def on_error(self, message): print(f'[task_{task_id}] Error: {message}') def on_data(self, data): self.file.write(data) def on_close(self): if hasattr(self, 'file'): self.file.close() callback = Callback() # Borrow a pre-connected synthesizer from the pool synth = pool.borrow_synthesizer( model='cosyvoice-v3-flash', voice='longanyang', callback=callback ) try: synth.call(text) complete_event.wait() print(f'[task_{task_id}] First packet delay: ' f'{synth.get_first_package_delay()} ms') # Return the synthesizer to the pool for reuse pool.return_synthesizer(synth) except Exception as e: print(f'[task_{task_id}] Failed: {e}') synth.close() # Do not return failed objects # Run concurrent tasks texts = ["First sentence.", "Second sentence.", "Third sentence."] threads = [threading.Thread(target=synthesize, args=(t, i)) for i, t in enumerate(texts)] for t in threads: t.start() for t in threads: t.join() pool.shutdown() ``` Never return a synthesizer to the pool if the task failed or is still running. Close it manually instead. ### Java: Connection pool + object pool {#java-connection-pool-object-pool} The Java SDK uses OkHttp3 connection pooling (enabled by default) plus an optional Apache Commons Pool2 object pool for `SpeechSynthesizer` instances. **Step 1: Configure connection pool via environment variables** | Variable | Default | Recommendation | | ------------------------------------------- | ------- | -------------------------- | | `DASHSCOPE_CONNECTION_POOL_SIZE` | 32 | 2x peak concurrency | | `DASHSCOPE_MAXIMUM_ASYNC_REQUESTS` | 32 | Match connection pool size | | `DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST` | 32 | Match connection pool size | ```bash export DASHSCOPE_CONNECTION_POOL_SIZE=2000 export DASHSCOPE_MAXIMUM_ASYNC_REQUESTS=2000 export DASHSCOPE_MAXIMUM_ASYNC_REQUESTS_PER_HOST=2000 ``` **Step 2: Add commons-pool2 dependency** ```xml org.apache.commons commons-pool2 the-latest-version ``` ```gradle implementation group: 'org.apache.commons', name: 'commons-pool2', version: 'the-latest-version' ``` **Step 3: Create and use the object pool** | Variable | Default | Recommendation | | ----------------------------------- | ------- | -------------------------------------------------------------- | | `SAMBERT_OBJECTPOOL_SIZE` (Sambert) | 500 | 1.5x-2x peak concurrency, must not exceed connection pool size | ```java import com.alibaba.dashscope.audio.tts.SpeechSynthesisParam; import com.alibaba.dashscope.audio.tts.SpeechSynthesizer; import org.apache.commons.pool2.BasePooledObjectFactory; import org.apache.commons.pool2.PooledObject; import org.apache.commons.pool2.impl.DefaultPooledObject; import org.apache.commons.pool2.impl.GenericObjectPool; import org.apache.commons.pool2.impl.GenericObjectPoolConfig; // Factory class SynthesizerFactory extends BasePooledObjectFactory { public SpeechSynthesizer create() { return new SpeechSynthesizer(); } public PooledObject wrap(SpeechSynthesizer obj) { return new DefaultPooledObject<>(obj); } } // Pool (global singleton) GenericObjectPoolConfig config = new GenericObjectPoolConfig<>(); config.setMaxTotal(1200); config.setMaxIdle(1200); config.setMinIdle(1200); GenericObjectPool pool = new GenericObjectPool<>(new SynthesizerFactory(), config); // Usage in each task SpeechSynthesizer synth = pool.borrowObject(); try { // ... configure params and call synth pool.returnObject(synth); } catch (Exception e) { synth = null; // Do not return on failure } ``` Reference server sizing: a 4-core 8 GiB machine can handle \~600 concurrent Sambert TTS tasks with an object pool of 1200 and a connection pool of 2000. ## Best practices {#best-practices} - **Java SDK**: Set `connectionPoolSize` and `maximumAsyncRequests` based on your concurrent workload. Too few connections cause blocking; too many increase server load. - **Python SDK**: Use `with` statements to manage the Session lifecycle and ensure proper resource cleanup. - **Choose the right method**: Use async calls for async applications (like asyncio or FastAPI). Use sync calls for traditional applications. - **WebSocket object pools**: Never return a synthesizer to the pool if the task failed or is still running. Close it manually instead. ## Performance monitoring {#performance-monitoring} Track these metrics to maintain healthy production TTS services: | Metric | Description | Target | | ---------------------- | -------------------------------------- | ---------------------- | | First packet delay | Time from request to first audio chunk | \< 500 ms | | End-to-end latency | Total time for complete synthesis | Depends on text length | | Error rate | Percentage of failed requests | \< 0.1% | | Pool utilization | Borrowed objects / pool size | 60%-80% at peak | | Connection reuse ratio | Reused connections / total requests | > 95% | Access these metrics from the SDK: ```python # TTS print(f"Request ID: {synthesizer.get_last_request_id()}") print(f"First packet delay: {synthesizer.get_first_package_delay()} ms") ``` ```java // TTS System.out.println("Request ID: " + synthesizer.getLastRequestId()); System.out.println("First packet delay: " + synthesizer.getFirstPackageDelay() + " ms"); ``` ## Production checklist {#production-checklist} Before going live, verify the following: - [ ] API Key stored in environment variable, not hardcoded. - [ ] Connection pool and object pool sizes configured for expected peak load. - [ ] Pool sizes do not exceed your account's QPS limit. - [ ] Error handling returns failed objects to disposal (not back to pool). - [ ] Graceful shutdown calls `pool.shutdown()` (Python) or pool close (Java). - [ ] WebSocket connections use the correct endpoint (`wss://maas.qwencloudapi.com/...`). - [ ] Monitoring dashboards track first-packet delay, error rate, and pool utilization. - [ ] Load tested with 2x expected peak concurrency. - [ ] Retry logic with exponential backoff for transient failures. ## Related {#related} - [Text to Speech](/developer-guides/speech/tts) -- TTS models, parameters, and streaming modes. - [Realtime streaming](/developer-guides/speech/realtime-streaming) -- realtime TTS streaming guide. - [Improve recognition accuracy](/developer-guides/accuracy-tuning/speech-recognition) -- ASR optimization including high-concurrency ASR patterns. # Accuracy tuning Source: https://docs.qwencloud.com/developer-guides/accuracy-tuning/overview > Maximize correctness and consistent behavior across text, image, video, speech, and vision models on QwenCloud "Accuracy" means different things for different modalities: for text generation it means factually correct and well-formatted answers; for image and video generation it means faithfully matching the prompt's intent with high visual quality; for speech synthesis it means natural-sounding audio with the right voice characteristics; and for vision or omni models it means correctly interpreting visual inputs. The underlying optimization approach, however, is the same across all of them. This guide walks through a structured approach to diagnosing and fixing accuracy issues — from prompt engineering to RAG to fine-tuning — so you can move from a working prototype to a reliable production system. While much of the detailed guidance focuses on text generation, each section includes strategies for other modalities where applicable. ## The optimization framework {#the-optimization-framework} Think of accuracy optimization along two axes: - **Context optimization** — the model lacks knowledge or guidance. For text models, fix this with better prompts or retrieval-augmented generation. For image/video models, fix this with more descriptive prompts, reference images, or style descriptors. For speech, fix this with model selection and voice configuration. This maximizes correctness. - **Model optimization** — the model behaves inconsistently. For text models, fix this with few-shot examples or fine-tuning. For generation models, fix this with seed pinning and consistent parameter sets. This maximizes consistency. Most real-world applications need improvements on both axes. A typical optimization journey looks like this: 1. Start with prompt engineering — get the best results possible with clear instructions and examples 2. Build an evaluation set to measure progress objectively 3. Diagnose whether the problem is missing knowledge, inconsistent behavior, or both 4. Add RAG if the model needs external information 5. Add fine-tuning if the model needs to learn new patterns 6. Combine techniques and iterate ## Prompt engineering {#prompt-engineering} Prompt engineering is always the first step. It requires no infrastructure, gives immediate feedback, and often solves more than you expect. | Strategy | When to use | Example | | ------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------- | | **Be specific** | Model gives vague or off-target answers | Instead of "Summarize this", say "Summarize this article in 3 bullet points, each under 20 words" | | **Add context** | Model lacks domain knowledge | Include relevant reference text, definitions, or constraints in the system prompt | | **Use few-shot examples** | Model format or style is inconsistent | Provide 2-5 input/output examples that demonstrate the exact behavior you want | | **Chain of thought** | Model makes reasoning errors | Add "Think step by step" or provide a worked example showing the reasoning process | | **Set constraints** | Model produces unwanted content | Explicitly state what to include, exclude, and how to handle edge cases | For detailed prompt engineering techniques, see [Text generation prompt engineering](/developer-guides/accuracy-tuning/text-generation). Long-context models like qwen3-max support inputs up to 256K tokens, but information placed in the middle of very long contexts may receive less attention than information at the beginning or end. Put your most important context — instructions, key reference material — at the start or end of the prompt. ### Prompt engineering for other modalities {#prompt-engineering-for-other-modalities} **Image generation** - Use a structured prompt formula: Subject + Setting + Style + Mood + Technical details. For example, "A golden retriever sitting in a sunlit garden, watercolor style, warm and peaceful, soft focus background." See [Image generation prompt engineering](/developer-guides/accuracy-tuning/image-generation) for detailed techniques. - Use negative prompts to exclude common defects such as blurriness, extra limbs, or text artifacts. - The `prompt_extend` (prompt rewriting) feature can enrich short prompts automatically, but adds 3-5 seconds of latency. Enable it during exploration, disable it in production when you have well-crafted prompts. - Model selection matters: Qwen-Image excels at text rendering within images, while Wan produces more photorealistic results. See [Text-to-image](/developer-guides/image-generation/text-to-image) for model comparisons. **Video generation** - Structure prompts as Entity + Scene + Motion. Explicitly describe the motion you want -- the model will not infer movement from a static scene description. See [Video generation prompt engineering](/developer-guides/accuracy-tuning/video-generation). - Use multi-shot mode to maintain subject consistency across scenes. See [Text-to-video](/developer-guides/video-generation/text-to-video). - Use negative prompts to suppress visual artifacts and fix a `seed` value to ensure reproducible results during iteration. **Vision and omni models** - Optimize input image and video quality: crop to the region of interest and ensure adequate resolution for the details you need the model to analyze. - Place the most critical question at the beginning or end of your prompt for best attention. - For text extraction from images, use the dedicated OCR endpoint for higher accuracy. See [OCR and text extraction](/developer-guides/multimodal/ocr). **Speech** - For text-to-speech (TTS), match the model to your scenario: use `instruct` models for emotional expression and fine-grained control, `flash` models for low-latency short text, and `vd` models when you need to design a custom voice from a text description. See [Speech synthesis](/developer-guides/speech/tts). - With instruct TTS models, use natural language instructions to control speech rate, emotion, and character (such as "Speak slowly in a warm, friendly tone"). - For automatic speech recognition (ASR), ensure audio input is clear with minimal background noise. For large files, pass a URL rather than Base64-encoded data to avoid request size limits. See [Speech recognition](/developer-guides/speech/asr). ## Build an evaluation set {#build-an-evaluation-set} Before optimizing, you need a way to measure improvement. Build an evaluation set of 30-50 question-answer pairs that represent your real use case. Each pair should include: - **Input**: The exact prompt (including system message and any context) you would send to the model - **Expected output**: The correct or ideal response - **Evaluation criteria**: How you judge whether the response is acceptable Run your evaluation set against the current model to establish a baseline score. Then re-run it after each change to confirm the change actually helps. **Automated evaluation approaches** Manual review does not scale. Consider these automated approaches: | Approach | Best for | How it works | | ------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------- | | **Exact match** | Classification, extraction, yes/no tasks | Compare model output directly against the expected answer | | **ROUGE / BERTScore** | Summarization, translation | Measure token overlap or semantic similarity between model output and reference | | **LLM-as-judge** | Open-ended generation, complex tasks | Use a capable model like qwen3-max to score outputs against your rubric | | **Task-specific metrics** | Domain-specific tasks | Custom metrics (such as valid JSON, correct SQL syntax, entity coverage) | For tasks where correctness is nuanced, LLM-as-judge with a clear scoring rubric often provides the best signal-to-noise ratio. ### Evaluating non-text modalities {#evaluating-non-text-modalities} - **Image and video generation**: Score outputs on a 1-5 scale across dimensions such as prompt faithfulness, visual quality, text clarity (if applicable), and absence of artifacts. Build a rubric with reference examples for each score level. - **Speech (TTS)**: Use Mean Opinion Score (MOS) testing across naturalness, intelligibility, and voice similarity (for cloned voices). Have multiple raters evaluate each sample. - **Speech (ASR)**: Measure Word Error Rate (WER) against ground-truth transcriptions on a representative audio test set. - **Vision and omni**: Use an LLM-as-judge approach -- send the model's output along with the source image and expected answer to a capable text model for automated scoring. ## Diagnose the problem {#diagnose-the-problem} Once you have evaluation results, categorize failures into two types: - **Missing knowledge (context problem)** — The model does not have the information it needs. For text, it may hallucinate facts or give generic answers. For image/video generation, this manifests as prompts that lack sufficient detail, producing outputs that miss the intended subject, style, or composition. Fix this with RAG (for text/vision) or richer prompts and reference media (for generation tasks). - **Inconsistent behavior (learning problem)** — The model has the information but does not reliably use it. For text, it may format outputs inconsistently or ignore instructions. For image/video generation, this manifests as varying styles, compositions, or quality across runs with the same prompt. Fix this with few-shot examples, fine-tuning (text), or seed pinning and parameter stabilization (generation). These categories are complementary, not mutually exclusive. A single application can have both problems — and often does. Diagnose each failure case individually to choose the right fix. ## Retrieval-augmented generation (RAG) {#retrieval-augmented-generation-rag} RAG injects relevant external knowledge into each request at inference time. Instead of relying solely on what the model learned during training, you retrieve the most relevant documents from your knowledge base and include them in the prompt. RAG primarily applies to text and vision tasks. For image and video generation, the equivalent approach is providing reference images, detailed style descriptions, or audio samples to guide the output. Use RAG when: - The model needs information that changes frequently (product catalogs, knowledge bases, policies) - The model needs proprietary or domain-specific data not in its training set - You need to cite sources or ground responses in specific documents - For vision tasks, the model needs to analyze images against a reference knowledge base (such as identifying products from a catalog, verifying document formats, or comparing visual assets against brand guidelines) ### Evaluate your RAG pipeline {#evaluate-your-rag-pipeline} RAG accuracy depends on two things: retrieval quality and generation quality. Evaluate them separately: | Metric | What it measures | How to check | | --------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | | **Retrieval precision** | Are the retrieved documents relevant? | Sample 50 queries, check if top-3 results contain the needed information | | **Retrieval recall** | Are all relevant documents found? | For known-answer questions, verify the source document appears in results | | **Generation faithfulness** | Does the model stick to retrieved content? | Check if answers are grounded in the provided context, not hallucinated | | **End-to-end accuracy** | Does the full pipeline give correct answers? | Run your evaluation set through the complete RAG pipeline | ### Retrieval optimization tips {#retrieval-optimization-tips} - **Chunk size matters** — Chunks that are too small lose context; chunks that are too large dilute relevance. Start with 200-500 tokens and experiment. - **Use reranking** — A two-stage pipeline (fast retrieval then precise reranking) significantly improves precision without sacrificing recall. - **Embed queries and documents consistently** — Use the same embedding model and preprocessing for both indexing and querying. - **Add metadata filters** — Filter by date, category, or source before semantic search to narrow the candidate set. To build RAG pipelines with QwenCloud: - [Text embedding](/developer-guides/embeddings/embedding) — Generate embeddings for semantic search - [Reranking](/developer-guides/embeddings/reranking) — Improve retrieval precision with a reranking model ## Combining techniques {#combining-techniques} The most effective production systems combine prompt engineering and RAG: - **Prompt engineering + RAG** — Clear instructions tell the model how to use the retrieved context. Few-shot examples show the expected format. - **Structured output + RAG** — Use [structured output](/developer-guides/text-generation/structured-output) to enforce consistent response formats when processing retrieved documents. When combining techniques, keep two principles in mind: 1. **More context can add noise.** Retrieving too many documents or stuffing too much information into the prompt can confuse the model. Always validate that adding context actually improves your evaluation scores. 2. **Exhaust simpler methods first.** Prompt engineering is fast and free. RAG requires moderate effort. Move to the next technique only when the current one plateaus. ## How much accuracy is good enough {#how-much-accuracy-is-good-enough} ### Business perspective {#business-perspective} Perfect accuracy is rarely achievable or necessary. The right target depends on the cost of errors versus the cost of improvement. Consider a customer service scenario: | Accuracy level | Behavior | Business impact | | -------------- | ------------------------------------------------------- | --------------------------------------------------------------------- | | **80%** | Handles common questions correctly, fails on edge cases | Reduces support volume but requires human review for \~20% of queries | | **90%** | Handles most questions including some edge cases | Significant cost savings, occasional escalations | | **95%** | Handles nearly all questions correctly | Near-full automation, rare human intervention | | **99%** | Near-perfect responses | Diminishing returns — the last 4% may cost more than the first 95% | The jump from 90% to 95% often requires more effort than the jump from 0% to 90%. Decide where the marginal cost of improvement exceeds the marginal value. ### Technical perspective {#technical-perspective} Design your system to fail gracefully when the model gets it wrong: - **Confidence thresholds** — If the model is uncertain, escalate to a human or ask for clarification rather than guessing. - **Output validation** — Check model outputs against schemas, business rules, or sanity checks before acting on them. - **Fallback paths** — Provide a graceful degradation path (such as "I'm not sure, let me connect you with a specialist") rather than a wrong answer. - **Monitoring** — Track accuracy metrics in production and set alerts for degradation so you can catch regressions early. ## Next steps {#next-steps} - [Text generation prompt engineering](/developer-guides/accuracy-tuning/text-generation) — Detailed prompt engineering techniques - [Image generation prompt engineering](/developer-guides/accuracy-tuning/image-generation) — Craft effective prompts for image generation - [Video generation prompt engineering](/developer-guides/accuracy-tuning/video-generation) — Craft effective prompts for video generation - [Speech synthesis](/developer-guides/speech/tts) — TTS model selection and voice configuration - [Vision understanding](/developer-guides/multimodal/vision) — Image and video understanding with vision models - [Text embedding](/developer-guides/embeddings/embedding) — Build RAG pipelines with embedding models - [Reranking](/developer-guides/embeddings/reranking) — Improve retrieval quality - [Structured output](/developer-guides/text-generation/structured-output) — Get consistent, parseable model outputs - [Model selection](/developer-guides/getting-started/model-selection) — Pick the right model for your task - [Cost optimization](/developer-guides/run-and-scale/cost-optimization) — Reduce spending while maintaining quality # Text-to-text Source: https://docs.qwencloud.com/developer-guides/accuracy-tuning/text-generation > Design effective prompts ## Design effective prompts {#design-effective-prompts} ### Write clear, specific instructions {#write-clear-specific-instructions} Vague prompts produce vague results. The more context and constraints you provide, the closer the output matches your expectations. Think of it like delegating a task: a one-line request leaves too much room for interpretation, while detailed instructions with clear goals produce exactly what you need. Clear, specific prompts are the single most important factor in getting useful output from an LLM. **Example: Code generation task** | **Vague prompt** | **Clear, specific prompt** | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Write a Python function to process data. | Write a Python function that reads a CSV file, filters rows where the `status` column equals `"active"`, and returns a list of dictionaries. Include type hints, handle the case where the file does not exist, and use the `csv` module from the standard library. | The specific prompt defines the input format, expected output, error handling, and library constraints -- enough for the model to produce usable code on the first try. **Example: Content generation task** | **Vague prompt** | **Clear, specific prompt** | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Help me write a product announcement. | Write a 200-word product announcement for "Zephyr Z9", a lightweight portable phone by Bailian. Highlight its ultra-thin design, high-performance specs, and ease of use. Target tech-savvy consumers on social media. Keep the tone energetic and concise. | ### Structure prompts with a framework {#structure-prompts-with-a-framework} A prompt framework helps you systematically provide the information an LLM needs. Instead of guessing what to include, use these six elements as a checklist: Prompt framework diagram

| **Element** | **Purpose** | **Example** | | ------------- | ------------------------------------------- | ------------------------------------------------------------ | | **Context** | Background information relevant to the task | "You are reviewing pull requests for a Python microservice." | | **Objective** | The specific task to complete | "Identify potential bugs and suggest fixes." | | **Style** | Writing style or persona | "Write as a senior backend engineer." | | **Tone** | Emotional quality of the output | "Professional but constructive." | | **Audience** | Who reads the output | "Junior developers on the team." | | **Response** | Desired output format | "A numbered list of issues with code suggestions." | Use `#` delimiters to mark each section in your prompt: ```plaintext #Context# You are reviewing pull requests for a Python microservice that handles user authentication. The codebase uses FastAPI and SQLAlchemy. #Objective# Review the following code diff and identify potential security vulnerabilities, performance issues, and style violations. #Style# Write as a senior backend engineer conducting a thorough code review. #Tone# Professional but constructive -- explain why each issue matters. #Audience# Junior developers who are learning secure coding practices. #Response# A numbered list of findings. For each finding, include: - The specific line or code block - Why it is a problem - A suggested fix with code ``` Not every prompt needs all six elements. Adapt the framework to your task. The examples throughout this guide use different subsets depending on the scenario. ## Optimize prompts {#optimize-prompts} ### Provide output examples {#provide-output-examples} Including examples of expected output helps the model match your format, style, and level of detail. This technique -- known as few-shot prompting -- also improves consistency across multiple runs. **Example: Structured data extraction** ```plaintext #Context# Extract structured information from user support tickets. #Objective# Parse each ticket into a JSON object. #Examples# Input: "My order #12345 arrived damaged. I want a refund." Output: { "order_id": "12345", "issue_type": "damaged_item", "requested_action": "refund" } Input: "I can't log in to my account. I've tried resetting my password twice." Output: { "order_id": null, "issue_type": "login_failure", "requested_action": "account_recovery" } #Task# Now parse this ticket: Input: "Order #67890 has been stuck in 'processing' for 5 days. Please expedite or cancel it." ``` The model learns the JSON schema, field naming conventions, and how to infer `issue_type` and `requested_action` from natural language -- all from the examples alone. ### Break complex tasks into steps {#break-complex-tasks-into-steps} For complex tasks, define explicit steps for the model to follow -- not just the desired result. Step-by-step instructions prevent the model from skipping intermediate reasoning. **Example: Math word problem** ```plaintext #Context# Timmy leaves home at 8:00 AM, walking at 50 meters per minute. After 12 minutes, his father notices Timmy forgot his homework and chases him on a bicycle at 200 meters per minute. After catching up, the father carries Timmy on the bicycle for the rest of the trip. The bicycle distance is 5 times the walking distance. #Objective# Calculate the arrival time. #Steps# 1. Calculate how far Timmy walks before his father catches up. 2. Determine how long it takes the father to catch up. 3. Calculate the remaining bicycle distance and travel time. 4. Add up all time intervals to find the arrival time. ``` **Model output (following the steps):** ```plaintext Step 1: Timmy walks for 12 minutes before his father starts: 12 min * 50 m/min = 600 m head start Step 2: Father's relative speed: 200 - 50 = 150 m/min Catch-up time: 600 m / 150 m/min = 4 minutes Timmy walks an additional: 4 min * 50 m/min = 200 m Total walking distance: 600 + 200 = 800 m Step 3: Bicycle distance: 800 m * 5 = 4,000 m Bicycle time: 4,000 m / 200 m/min = 20 minutes Step 4: Total time: 12 + 4 + 20 = 36 minutes Arrival: 8:00 AM + 36 min = 8:36 AM ``` Without the `#Steps#` section, the model may skip intermediate calculations and produce an incorrect answer. ### Use delimiters to separate content {#use-delimiters-to-separate-content} When a prompt contains multiple blocks of content -- instructions, input data, and examples -- use delimiters to mark clear boundaries. This helps the model distinguish your instructions from the content it should process. Use character sequences that rarely appear in natural language: `###`, `===`, or `>>>`. **Example: Text summarization** ```plaintext Summarize each section of the following movie review separately. Produce one summary sentence per section. ### Zhang Zhiqiang was once spirited and energetic, but life's pressures pushed him off course. An impulsive decision in middle age transformed him from his family's pride into a social outcast. ### This was just the beginning. A series of unexpected events forced him to confront himself. He chose to start over as a delivery driver, navigating city streets to rebuild his life. ### Along the way, he found like-minded companions. Through their shared struggles, he rediscovered his courage and purpose, forging a new direction for his life. ### ``` Without delimiters, the model treats the entire review as a single block and produces one generic summary. With delimiters, it identifies three distinct sections and generates three related summaries that follow the narrative arc. ### Guide the model to reason step by step {#guide-the-model-to-reason-step-by-step} For tasks involving logic, math, or multi-step analysis, have the model show its reasoning before stating a conclusion. Two effective techniques: #### Chain of Thought (CoT) {#chain-of-thought-cot} CoT is a relatively simple method that can significantly improve the reasoning of LLMs in complex scenarios. Ask the model to explain its thinking before producing a final answer. **Example: JSON validation** ```plaintext #Context# JSON input: {"web-app": { "servlet": [ { "servlet-name": "cofaxEmail", "servlet-class": "org.cofax.cds.EmailServlet", "init-param": { "mailHost": "mail1", "mailHostOverride": "mail2"}}, { "servlet-name": "cofaxTools", "servlet-class": "org.cofax.cms.CofaxToolsServlet", "init-param": { "templatePath": "toolstemplates/", "log": 1, "logLocation": "/usr/local/tomcat/logs/CofaxTools.log", "logMaxSize": ""}}], "servlet-mapping": { "cofaxEmail": "/cofaxutil/aemail/*", "cofaxTools": "/tools/*"}, "taglib": { "taglib-uri": "cofax.tld", "taglib-location": "/WEB-INF/tlds/cofax.tld"}}} #Objective# Verify whether this JSON meets all three requirements: 1. Every servlet has an init-param block. 2. Every key in servlet-mapping matches a servlet-name. 3. The cofaxTools servlet has exactly three parameters starting with "log", and the "log" parameter value is less than 10. #Response# First, explain your reasoning for each requirement. Then state whether all requirements are met. ``` Adding "explain your reasoning" produces a structured analysis where the model evaluates each requirement individually -- catching edge cases (like the empty string value of `logMaxSize`) that it would miss with a yes/no-only output. #### Prompt chaining {#prompt-chaining} Break a complex problem into a sequence of simpler questions across multiple turns. Each answer feeds into the next question, guiding the model along a controlled reasoning path. Prompt chaining takes more effort to set up than CoT but performs better and has higher accuracy. It is particularly suitable for tasks that are logically complex but can be broken down according to fixed patterns. **Example: Multi-step math (same Timmy problem, three turns)** **Turn 1:** ```plaintext #Context# Timmy leaves at 8:00 AM walking at 50 m/min. After 12 minutes, his father chases on a bicycle at 200 m/min. The bicycle distance is 5 times the walking distance. #Question# When does the father catch Timmy, and how far has Timmy walked? ``` **Model:** "The father catches Timmy at 8:16 AM, after Timmy has walked 800 meters." **Turn 2:** ```plaintext How far does Timmy travel by bicycle to reach his grandparents' house? ``` **Model:** "Bicycle distance = 800 m \* 5 = 4,000 meters." **Turn 3:** ```plaintext What time does Timmy arrive? ``` **Model:** "Bicycle time = 4,000 m / 200 m/min = 20 minutes. Total time = 16 + 20 = 36 minutes. Arrival: 8:36 AM." Each turn builds on verified intermediate results, reducing the chance of compounding errors. Other reasoning techniques include Tree of Thoughts (ToT) and Boosting of Thoughts. Choose the technique that matches your task complexity and accuracy requirements. ## Test and iterate {#test-and-iterate} Prompt engineering is iterative. Rarely does the first version of a prompt produce the best results. Prompt iteration cycle diagram

Follow this cycle: 1. **Define your goal.** Decide what good output looks like before writing the prompt. 2. **Write an initial prompt.** Apply the techniques from this guide: be specific, use a framework, and provide examples. 3. **Test with diverse inputs.** Run the prompt against multiple real-world scenarios, including edge cases. 4. **Analyze failures.** Identify where output falls short: wrong format, missing information, incorrect reasoning, or inconsistent tone. 5. **Refine the prompt.** Adjust one element at a time to measure the effect of each change. 6. **Repeat.** Continue until output consistently meets your quality bar. Beyond prompt design, user feedback is essential. After deploying a prompt in production, monitor real interactions and refine based on patterns in user corrections and edge cases you did not anticipate. ## Example: Optimize a multilingual HR assistant {#example-optimize-a-multilingual-hr-assistant} **Background:** A Qwen3.5-Flash-based HR assistant for a multinational company was not consistently responding in the user's language. The system prompt needed restructuring. ### Before optimization {#before-optimization} ```plaintext # Role You are an efficient HR AI assistant, specifically responsible for answering company internal questions about policies, attendance systems, annual leave arrangements, and other related issues. ## Skills ### Skill 1: Policy interpretation - Accurately interpret company policy documents and provide clear, concise policy explanations to colleagues. ### Skill 2: Attendance Q&A - Answer all questions related to employee attendance, including clock-in rules, handling of late arrivals and early departures, leave procedures, etc. ### Skill 3: Annual leave management consultation - Explain annual leave application conditions, accumulation rules, validity period, and approval process. ## Limitations - Respond in the same language as the user's question. - Limited to HR-related questions. - Do not involve queries of personal privacy data. ``` **Issues:** - Loose structure with a redundant `## Limitations` section - The `${documents}` knowledge base block was embedded inline, making it hard for the model to distinguish instructions from reference content - Language-matching instructions were buried in limitations ### After optimization {#after-optimization} ```plaintext #Context# You are an HR AI assistant for a multinational company. You answer questions about policy interpretation, attendance rules, and annual leave management. Below are the company policy documents: ====== ${documents} ====== #Objective# 1. Only answer questions about policy interpretation, attendance, and annual leave. 2. When a question is in scope but the knowledge base does not cover it, direct the user to contact the HR department. 3. For each category, follow these guidelines: - Policy interpretation: Locate the relevant clause and provide a clear, concise explanation. - Attendance: Cover clock-in rules, late arrival handling, and leave procedures. - Annual leave: Explain eligibility, accrual rules, approval process, and help calculate remaining balance. 4. Do not access or disclose personal employee data. #Multilingual requirements# - If the question is not in Chinese, translate it to Chinese to search the knowledge base, then convert the retrieved content back to the question's language for output. #Response# - Use only standard ASCII characters in all output. - Match the output language to the input language. ``` **What changed:** - **Framework applied.** Restructured using `#Context#`, `#Objective#`, `#Multilingual requirements#`, and `#Response#` sections. - **Delimiters added.** Wrapped `${documents}` in `======` delimiters to separate reference data from instructions. - **Constraints distributed.** Moved constraints into their relevant sections (language rules into `#Multilingual requirements#`, scope limits into `#Objective#`). These changes resolved the language-consistency issue because the model could clearly identify the multilingual instruction as a distinct, high-priority directive rather than a buried afterthought. # Text-to-image Source: https://docs.qwencloud.com/developer-guides/accuracy-tuning/image-generation > Better Wan image results Write effective prompts to generate high-quality images with the [Text-to-image guide](/developer-guides/image-generation/text-to-image). This guide covers prompt structure, visual vocabulary, and practical examples so you can consistently get the results you want. ## Prompt structure {#prompt-structure} The more complete and precise your prompt, the higher the quality of the generated image. Here are two prompt formulas for different requirements. ### Basic formula {#basic-formula} **Target users**: New users trying AI creation for the first time, and users using AI as a source of inspiration. Use this formula for quick exploration and creative experimentation. **Prompt = Subject + Setting + Style** | Element | What it controls | Examples | | ----------- | -------------------------------------------------------------------- | ------------------------------------------- | | **Subject** | Main object -- person, animal, plant, object, or imaginary creature | "a golden retriever", "a medieval castle" | | **Setting** | Where the subject is -- indoor/outdoor, season, weather, time of day | "in a snowy forest", "at sunset on a beach" | | **Style** | Artistic look -- realistic, abstract, painterly | "watercolor style", "cinematic photography" | **Example**

Prompt	Result
25-year-old Chinese girl, round face, looking at the camera, elegant ethnic costume, commercial photography, outdoor, cinematic lighting, half-body close-up, delicate light makeup, sharp edges.

### Advanced formula {#advanced-formula} **Target users**: Users with some experience in AI image generation. Use this formula when you want fine-grained control over camera, mood, and detail. **Prompt = Subject + Setting + Style + Camera + Atmosphere + Detail modifiers** | Element | What it controls | Examples | | -------------------- | ----------------------------------------------------- | ------------------------------------------------------- | | **Subject** | Main object with specific characteristics and actions | "a cute 10-year-old Chinese girl wearing a red dress" | | **Setting** | Detailed environmental characteristics | "surrounded by animal kingdom city street shops" | | **Style** | Specific artistic style or visual technique | "watercolor style", "Pixar style", "felt style" | | **Camera** | Shot size, angle, lens type, and composition | "close-up", "centered composition", "photographic lens" | | **Atmosphere** | Mood and emotional tone | "dreamy", "lonely", "majestic", "childlike wonder" | | **Detail modifiers** | Refinements for quality and aesthetics | "4K", "high resolution", "backlight", "natural" | **Example**

Prompt

Result

A panda made of wool felt, wearing a wide-brimmed hat, dressed in a blue police uniform vest, with a belt around the waist, carrying police equipment, wearing blue gloves, leather shoes, in a running posture, felt effect, surrounded by animal kingdom city street shops, premium filter, street lamps, animal kingdom, childlike wonder, adorable appearance, night, bright, natural, cute, 4K, felt material, photographic lens, centered composition, felt style, Pixar style, backlight.

### Structured prompt template {#structured-prompt-template} For maximum control, use the following dimensions as a checklist. Include only those relevant to your image. | Dimension | Description | Example values | | ---------------- | ------------------------- | ---------------------------------------------- | | **Subject** | Main focus of the image | "a cheetah", "an old lighthouse" | | **Action/Pose** | What the subject is doing | "running", "looking at the camera" | | **Style** | Artistic approach | "3D cartoon", "ink painting", "realistic" | | **Setting** | Background environment | "dense forest", "city street at night" | | **Lighting** | Light source and quality | "cinematic lighting", "backlight", "neon" | | **Atmosphere** | Mood or emotion | "serene", "dramatic", "whimsical" | | **Camera angle** | Viewing perspective | "eye level", "bird's eye", "low angle" | | **Shot size** | Subject framing | "extreme close-up", "medium shot", "long shot" | | **Lens** | Lens simulation | "macro", "telephoto", "fisheye" | ## Prompt parameters {#prompt-parameters} Text-to-image V2 prompt-related parameters: | Parameter | Location | Description | | ----------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `text` | `input.messages[].content[].text` | Positive prompt that describes the image to generate. Supports both Chinese and English. | | `negative_prompt` | `parameters.negative_prompt` | Negative prompt that specifies content to exclude from the image. | | `prompt_extend` | `parameters.prompt_extend` | Specifies whether to enable intelligent prompt rewriting. Defaults to `true`, which enables intelligent rewriting by an LLM. Keep the default for best results. | **Example request** ```json { "model": "wan2.6-t2i", "input": { "messages": [ { "role": "user", "content": [ { "text": "A flower shop with exquisite windows, beautiful wooden doors, and flowers on display" } ] } ] }, "parameters": { "negative_prompt": "people", "prompt_extend": true } } ``` ## Prompt vocabulary reference {#prompt-vocabulary-reference} The following sections provide ready-to-use keywords for five visual dimensions: shot size, perspective, lens type, style, and lighting. Add any keyword directly to your prompt. ### Shot size {#shot-size} Shot size controls how much of the subject fills the frame. It is generally divided into long shot, full shot, medium shot, close-up, and extreme close-up. | Shot type | When to use | Prompt keyword | | -------------------- | -------------------------------------------- | ------------------ | | **Extreme close-up** | Highlight facial details, textures, emotions | `extreme close-up` | | **Close-up** | Focus on a single subject with some context | `close-up` | | **Medium shot** | Balance subject and environment | `medium shot` | | **Long shot** | Emphasize environment, show scale | `long shot` | **Examples** **Extreme close-up**

High-definition camera, emotional photography, sunset, extreme close-up portrait.

**Close-up**

18-year-old Chinese girl, ancient costume, round face, looking at the camera, elegant ethnic costume, commercial photography, outdoor, cinematic lighting, half-body close-up, delicate light makeup, sharp edges.

**Medium shot**

Cinematic fashion glamour photography, young Asian woman, Chinese Miao girl, round face, looking at the camera, elegant dark ethnic costume, medium wide-angle lens, sunny, utopian, shot with a high-definition camera.

**Long shot**

Shows two small figures standing on a distant mountaintop against a magnificent snowy mountain background, with their backs to the camera, quietly admiring the sunset. The sunset's glow bathes the snow-capped mountains in a golden light, creating a stark contrast with the azure sky. The two people seem captivated by this spectacular natural scene, and the entire image is filled with tranquility and harmony.

### Perspective {#perspective} Perspective controls the camera angle relative to the subject. | Perspective type | When to use | Prompt keyword | | ---------------- | -------------------------------------- | ------------------------ | | **Eye level** | Natural, relatable viewpoint | `eye level perspective` | | **Bird's eye** | Overview, patterns, scale from above | `bird's eye perspective` | | **Low angle** | Dramatic, imposing, powerful subjects | `low angle` | | **Aerial** | Landscape overview, geographic context | `aerial perspective` | **Examples** **Eye level**

The image shows a grassland scene captured from an eye level perspective, where a flock of sheep leisurely graze on the lush green grass, their wool glowing with a warm golden hue in the weak morning sunlight, creating beautiful light and shadow effects.

**Bird's eye**

The scene depicts a view looking down at the ice lake from the air, with a small boat in the center, surrounded by vortex patterns and vibrant blue seawater. Spiral abyss, the scene is shot from above in a top-down perspective, showing intricate details such as ripples on the surface and layers beneath the snow-covered ground. Gazing out at the cold vast expanse. Creating an awe-inspiring sense of tranquility.

**Low angle**

Shows a spectacular scene in a tropical area, where tall coconut trees stand like towering giants, with lush branches pointing towards the blue sky. The camera uses a low angle perspective, making viewers feel as if they are standing under the trees, experiencing the majesty and vitality of nature. Sunlight filters through the gaps in the leaves, creating dappled light and shadow, adding a touch of mystery and romance. The entire image is filled with tropical flavor, making one almost smell the coconut fragrance and feel the pleasant breeze on their face.

**Aerial**

Shows heavy snow, village, roads, lights, trees. Aerial perspective, realistic effect.

### Lens type {#lens-type} Lens type simulates different camera lenses and their optical characteristics. | Lens type | When to use | Prompt keyword | | -------------------- | --------------------------------------------- | ----------------------- | | **Macro** | Tiny details, textures, small objects | `macro lens` | | **Ultra-wide angle** | Expansive landscapes, architectural interiors | `ultra-wide angle lens` | | **Telephoto** | Isolated subjects with blurred backgrounds | `telephoto lens` | | **Fisheye** | Exaggerated distortion, creative effects | `fisheye lens` | **Examples** **Macro**

Cherries, carbonated water, macro, professional color grading, clean sharp focus, commercial high quality, magazine winning photography, hyper realistic, uhd, 8K.

**Ultra-wide angle**

Island under blue sea and sky, sunlight filtering through tree leaves, casting dappled shadows. Ultra-wide angle lens.

**Telephoto**

Shows a cheetah standing in a lush forest under a telephoto lens, facing the camera, with the background cleverly blurred, making the cheetah's face the absolute focus of the image. Sunlight filters through the gaps in the leaves, creating dappled light and shadow effects on the cheetah, enhancing the visual impact.

**Fisheye**

Shows a scene where a woman stands and looks directly at the camera under the special perspective of a fisheye lens. Her image is exaggeratedly enlarged in the center of the frame, while the surroundings show strong distortion effects, creating a unique visual impact.

### Style {#style} Style defines the artistic look and rendering technique applied to the image. | Style | When to use | Prompt keyword | | -------------------- | ---------------------------------------- | ------------------------ | | **3D cartoon** | Animated characters, playful scenes | `3D cartoon style` | | **Post-apocalyptic** | Dystopian, ruined environments | `post-apocalyptic style` | | **Pointillism** | Impressionist dots, textured appearance | `pointillism` | | **Surrealism** | Dreamlike, impossible scenes | `surrealist style` | | **Watercolor** | Soft, painterly, translucent effects | `watercolor` | | **Clay** | Sculpted, tactile, handmade look | `clay style` | | **Realistic** | Photographic realism, lifelike detail | `realistic` | | **Ceramic** | Glazed, sculpted, porcelain-like | `ceramic` | | **3D** | Rendered, dimensional, CGI look | `3D`, `C4D rendering` | | **Ink painting** | Traditional East Asian brush art | `ink painting` | | **Origami** | Paper-folded, geometric, minimal | `origami` | | **Gongbi** | Fine-detail traditional Chinese painting | `Gongbi painting` | | **Chinese ink** | Ink wash with Chinese aesthetic | `Chinese ink style` | **Examples** **3D cartoon**

Female tennis player, short hair, white tennis outfit, black shorts, returning the ball from the side, 3D cartoon style.

**Post-apocalyptic**

City on Mars, post-apocalyptic style.

**Pointillism**

A cute white little house, thatched roof, a snow-covered prairie, bold use of pointillism, Monet feel, clear brushstrokes, blurred edges, primitive edge texture, low saturation colors, low contrast, Morandi colors.

**Surrealism**

A pink glowing river in a deep gray sea, with a minimalist, beautiful, and aesthetic atmosphere, cinematic lighting with a surrealist style.

**Watercolor**

Light watercolor, outside a cafe, bright white background, fewer details, dreamy, Studio Ghibli.

**Clay**

Clay style, little boy in a blue sweater, brown curly hair, dark blue beret, drawing board, outdoors, seaside, half-body shot.

**Realistic**

Basket, grapes, picnic cloth, hyper realistic still life photography, macro lens, Tyndall effect.

**Ceramic**

Shows a highly detailed ceramic dog lying quietly on a table with a delicate bell tied around its neck. Each strand of the dog's fur is intricately carved, and the details of its eyes, nose, and mouth are lifelike.

**3D**

Chinese dragon, cute Chinese dragon sleeping on white clouds, charming garden, in morning mist, close-up, front view, 3D, C4D rendering, 32k ultra high definition, 32k UHD, Chinese punk, 32k UHD, animal statue, octane rendering, ultra high definition.

**Ink painting**

Orchid, ink painting, white space, artistic conception, Wu Guanzhong style, delicate brushstrokes, texture of rice paper.

**Origami**

Origami masterpiece, kraft paper panda, forest background, medium shot, minimalism, backlight, best quality.

**Gongbi**

At dawn, a plum blossom stands proudly in the snow, with petals as delicate as silk, dewdrops lightly hanging, showcasing the exquisite beauty of Gongbi painting.

**Chinese ink**

Chinese ink style, a man with long black hair, golden hairpin, golden butterflies flying around, white clothing, high detail, high quality, deep blue background, with faintly visible ink bamboo forest in the background.

### Lighting {#lighting} Lighting sets the mood, atmosphere, and visual depth of the image. | Lighting type | When to use | Prompt keyword | | ----------------- | -------------------------------------------- | ------------------------------------ | | **Natural light** | Outdoor scenes, realistic warmth | `sunlight`, `moonlight`, `starlight` | | **Backlight** | Silhouettes, halo effects, dramatic contours | `backlight` | | **Neon light** | Urban night scenes, cyberpunk aesthetics | `neon light` | | **Ambient light** | Soft, diffused, atmospheric glow | `ambient light` | **Examples** **Natural light**

The image shows morning sunlight streaming onto the ground of a dense forest, with silver-white rays penetrating the treetops, creating dappled light and shadow, creating a realistic and serene atmosphere.

**Backlight**

Shows that in a backlit environment, the model's contour lines become more distinct, with golden light and silk surrounding the model, creating a dreamlike halo effect. The entire scene is full of artistic atmosphere, showcasing high-level photography techniques and creativity.

**Neon light**

City street scene after rain, neon lights reflect colorful rays on the wet ground. Pedestrians hurry by with umbrellas, vehicles slowly drive through the bizarre streets, leaving colorful trails. The entire image is filled with the mystery and romance of the urban night, as if each raindrop is telling a story of the city.

**Ambient light**

Romantic artistic scene by the river at night, ambient lights gently illuminate the water surface, a group of lotus lanterns slowly drift toward the center of the river, the light and the rippling water surface reflect each other, creating a dreamlike visual effect.

# Text-to-video Source: https://docs.qwencloud.com/developer-guides/accuracy-tuning/video-generation > Craft better video prompts Scenarios: - [Text-to-video API reference](/api-reference/video-generation/wan-text-to-video/create-task) - [Image-to-video (first frame) API reference](/api-reference/video-generation/wan-image-to-video-first-frame/create-task) - [Image-to-video (first and last frames) API reference](/api-reference/video-generation/wan-image-to-video-first-last-frames/create-task) - [Reference-to-video API reference](/api-reference/video-generation/wan-reference-to-video/create-task) ## Prompt formulas {#prompt-formulas} Here, a prompt refers to a **positive prompt** that describes the visual content and motion in a video. The more accurate and detailed the description, the higher the quality of the generated video. ### Basic formula {#basic-formula} This formula is for users who are new to AI video generation or use it for creative inspiration. Simple and flexible prompts can produce more imaginative videos. > **Prompt = Entity + Scene + Motion** - **Entity** — The main subject of the video. It can be a person, animal, plant, object, or an imaginary object. - **Scene** — The environment where the entity is located. It includes the background and foreground and can be a real or imaginary setting. - **Motion** — The specific movement of the entity and other elements in the scene. This can range from a still scene to slight, large, local, or overall movement. ### Advanced formula {#advanced-formula} This formula is for users who have some experience with AI video generation. You can add richer and more detailed descriptions to the basic formula to enhance the video's texture, vividness, and narrative quality. > **Prompt = Entity (description) + Scene (description) + Motion (description) + Aesthetic control + Stylization** - **Entity description** — Describes the details of the entity's appearance. You can list adjectives or short phrases. For example, "a young Miao girl with black hair in ethnic costume" or "a celestial fairy from another world, dressed in tattered yet magnificent clothes, with a pair of strange wings made of debris from ruins on her back." - **Scene description** — Describes the details of the entity's environment. You can list adjectives or short phrases. - **Motion description** — Describes the details of the motion, including its amplitude, speed, and effect. For example, "swaying violently," "moving slowly," or "shattering the glass." - **Aesthetic control** — Includes light source, lighting environment, shot size, camera angle, lens, and camera movement. For common cinematic terms, see the prompt dictionary below. - **Stylization** — Describes the visual style of the video. For example, "cyberpunk," "line art illustration," or "wasteland style." For common styles, see the prompt dictionary below. ### Image-to-video formula {#image-to-video-formula} Because the image already defines the entity, scene, and style, the prompt should focus on describing the desired motion and camera movements. > **Prompt = Motion + Camera movement** - **Motion description** — Describe the movement of elements in the image, such as people running or animals waving. You can use adjectives such as "quickly" or "slowly" to control the speed and intensity of the motion. - **Camera movement** — If you have specific requirements for camera movement, you can use prompts such as "camera pushes in" or "camera moves left." If you want the camera to remain still, you can use "fixed camera" to emphasize this. ### Sound formula (Wan 2.5/2.6) {#sound-formula-wan-2-5-2-6} With native audio capabilities, you can add descriptions for human voices, sound effects, and background music to your prompts for enhanced sound control. > **Prompt = Entity + Scene + Motion + Sound description (voice/sound effect/background music)** - **Sound description** — Describes the sound elements in the video and their changes over time. This guides the sound content and atmosphere to match the visual narrative precisely. This includes three main categories: - **Voice** = Character's lines + Emotion + Tone + Speed + Timbre + Accent - **Sound effect** = Source material + Action + Ambient sound - **Background music** = Background music/score + Style **Voice example:** A man is doing a stand-up comedy routine. He says, "Study hard and make progress every day," in a relaxed tone, at a moderate speed, with a clear voice, in American English. **Sound effect example:** A small glass ball falls from a table onto a wooden floor, making a "thud" sound in a quiet indoor environment. **BGM example:** On a rainy night, a spooky, narrow corridor has a window at the end, with suspenseful background music. ### Reference-to-video formula (Wan 2.6) {#reference-to-video-formula-wan-2-6} Wan 2.6 lets you generate videos by referencing the main character in an input video. You can reference the character's appearance, motion, and voice timbre. The character can be a person, cartoon, pet, or prop. > **Prompt = Character + Action + Lines + Scene** - **Character** — Reference the main character using an identifier such as character1. You can reference up to three characters at the same time. Each character can be referenced multiple times in the prompt to precisely control their behavior. - **Action** — Describe the motion of the character or other elements. This includes static states, changes in expression and emotion, body movements, external actions, and displacement. - **Lines** — The character's spoken content. This supports a single character speaking or a dialogue between multiple characters. - **Scene** — The environment where the character is located. It includes the background and foreground and can be a real or imaginary setting. **Example**: This is a whimsical fairytale scene. character1 is jumping and playing on the grass. character2 is playing the piano under a nearby apple tree. An apple falls on character2's head. character1 points at character2 and says happily, "You're going to become a scientist!". In this example, the reference video for character1 is a rabbit, and the reference video for character2 is a dog. Each reference video contains only a single character. ### Multi-shot formula (Wan 2.6) {#multi-shot-formula-wan-2-6} Wan 2.6 supports generating coherent narrative videos with multiple shots. You can use prompts to precisely control the shot structure, camera position, and duration. This ensures that key elements such as the entity, scene, and atmosphere remain consistent across shots. > **Prompt = Overall description + Shot number + Timestamp + Shot content** - **Overall description** — Briefly summarize the entire video content. State the story's theme, narrative style, main emotion, or core event. This helps the AI grasp the overall narrative direction. - **Shot number** — Assign a number to each shot to distinguish the sequence of different scenes or segments in the video. This helps organize the video structure clearly. - **Timestamp** — Specify the time range for each shot in the video. This ensures that the shot content corresponds to the video timeline and improves generation accuracy. - **Shot content** — Describe the specific behavior of the main character or object in each shot. This includes actions, speech, expressions, and posture. You can follow the general prompt writing style for a single shot. **Example:** This story is a short play about giving up and regaining hope, told from a third-person perspective. Shot 1 \[0--3 s] A boy sits alone in a corner of a playground, looking down at a letter in his hand. He sighs softly, his eyes filled with confusion. Shot 2 \[4--6 s] Hard cut transition, fixed camera position, focusing on the boy's eyes, which are glistening with tears, showing loss and helplessness. Shot 3 \[7--10 s] Hard cut transition, the scene changes to a simple classroom. A girl with a gentle and firm gaze, dressed in plain clothes, walks over to the boy with a warm and determined smile to comfort him. ## Prompt optimization techniques {#prompt-optimization-techniques} ### 1. Automatic optimization: Enable the prompt\_extend parameter {#1-automatic-optimization-enable-the-prompt-extend-parameter} When you call the API, enable the `prompt_extend` parameter. The system automatically optimizes and rewrites your positive prompt. This feature works well for short, general prompts, such as "A kitten plays with a snowball in the snow." For examples showing how to use `prompt_extend` in API calls, see the [Text-to-video](/developer-guides/video-generation/text-to-video) and [Image-to-video](/developer-guides/video-generation/image-to-video) developer guides. ### 2. Generate prompts using prompt formulas {#2-generate-prompts-using-prompt-formulas} When you need to precisely control image details, style, or complex dynamics, you can write prompts using the structured prompt formulas. You can provide the formulas as a system message to a large language model (LLM), such as qwen3.7-plus, to generate well-structured prompts. This example uses the OpenAI SDK. Before running, install the dependency: ```bash pip install openai ``` For more code examples, see [Overview of text generation models](/developer-guides/getting-started/text-generation-models). **Input example** ```python import os from openai import OpenAI try: client = OpenAI( # If you have not configured the environment variable, replace the following line with your API key: api_key="sk-xxx", api_key=os.getenv("DASHSCOPE_API_KEY"), base_url="https://maas.qwencloudapi.com/compatible-mode/v1", ) completion = client.chat.completions.create( model="qwen3.7-plus", messages=[ {"role": "system", "content": "You are a prompt optimization assistant. The prompt formula is: Prompt = Entity + Scene + Motion + Sound description (voice/sound effect/background music)\nSound description: Describes the sound elements in the video and their changes over time. It guides the sound content and atmosphere to match the visual narrative precisely. It mainly includes three categories: human voice, sound effects, and BGM.\nVoice = Character's lines + Emotion + Tone + Speed + Timbre + Accent\nExample: A man is doing a stand-up comedy routine. He says, \"Study hard and make progress every day,\" in a relaxed tone, at a moderate speed, with a clear voice, in American English.\nSound effect = Source material + Action + Ambient sound\nExample: A small glass ball falls from a table onto a wooden floor, making a \"thud\" sound in a quiet indoor environment.\nBackground music = Background music/score + Style\nExample: On a rainy night, a spooky, narrow corridor has a window at the end, with suspenseful background music."}, {"role": "user", "content": "A kitten plays with a snowball in the snow"}, ], ) print(completion.choices[0].message.content) # To view the full response, uncomment the following line # print(completion.model_dump_json()) except Exception as e: print(f"Error message: {e}") print("For more information, see the document: https://docs.qwencloud.com/api-reference/preparation/error-messages") ``` **Output example** ```text Entity: A fluffy kitten Scene: A snow-covered yard on a winter morning. The snow is thick and soft. There are frosted branches and a small snowman in the distance. Motion: The kitten rolls up a snowball with its front paws, clumsily pushing it forward. Suddenly, the snowball breaks apart, and the kitten jumps back in surprise. It then curiously approaches, sneezes, does a somersault, and continues to play by nudging the snowball with its head. Sound description: - Voice: None - Sound effects: The soft "crunch, crunch" of the kitten's paws on the snow; the "swish" of the snowball rolling; the "crack" as the snowball breaks; the kitten's cute, crisp "achoo!" sneeze; the "rustle" of snow falling as it tumbles. - Background music: A light and warm piano score with a nursery rhyme style. The rhythm is playful, like a small animal frolicking, creating a whimsical winter atmosphere. Full prompt: A fluffy kitten plays with a snowball in a snowy yard on a winter morning. It rolls up a snowball with its front paws, clumsily pushing it forward. The snowball suddenly breaks, and the kitten jumps back in surprise, sneezes, then curiously approaches and finally plays by nudging the snowball with its head and tumbling around. Sound effects include the "crunch" of paws on snow, the "swish" of the rolling snowball, the "crack" of it breaking, the kitten's "achoo!" sneeze, and the "rustle" of falling snow. The background music is a light, warm, nursery-rhyme-style piano score, creating a warm and adorable winter atmosphere. ``` ## Prompt dictionary {#prompt-dictionary} *All examples below were generated using Wan 2.2 unless noted otherwise. Sound generation examples use Wan 2.5 Preview.* ### Sound generation {#sound-generation} To generate videos with synchronized audio, describe human voices, ambient sounds, and other elements that match the video's visuals. #### Voice {#voice} ##### Single speaker

Complex text	Long paragraphs	Complex layouts

Poster design	Illustration design	Realistic photography

Portrait photography	Realistic photography	Painting styles

Text generation	Poster design	Image set generation

Capability	Input prompt	Input first or last frame	Output video
First frame to video	(0:00 - 0:03) Camera: Medium shot. Scene: A ink-wash bamboo forest scene from Image 1. A swordsman wearing a bamboo hat and dressed in a dark robe, his silhouette standing in the center surrounded by thick fog and swaying bamboo shadows. Action: The swordsman's left hand lightly rests on the sword hilt, bamboo leaves fall with the wind. Atmosphere: Silent, oppressive, with clearly visible ink-wash grain texture. > See full prompt in the collapsible section below the table.
First and last frame to video	\[One continuous take, slow aesthetic camera movement, no cuts, 15-second long shot, rock-color mineral pigment texture colliding with 3D rendering, cyan-blue × gilt gold contrasting colors] > See full prompt in the collapsible section below the table.	First frame Last frame

Capability	Input prompt	Input reference materials	Output video
Reference image	Using the lip gloss product in Image 1, generate a model swatch video, 15 seconds, vertical screen, highlighting the lip color effect
Reference image+video+audio	Seamlessly replace the male character from Image 1 into Video 1's female role. The character sits by the window, holding a phone to the ear. \[Voice and dialogue] Extract the voice characteristics from Audio 1, and have the character say the following lines: "Really? That sounds great! When are you coming back? I miss you so much." \[Lip-sync and expressions] The generated voice must precisely drive the character's lip movements with natural opening and closing. While speaking, include natural blinking, slight head nodding, and a sense of breathing. Facial micro-expressions must perfectly match the caring and nostalgic emotions in the dialogue. \[Lighting and scene] The character's face must naturally receive mixed lighting from warm indoor light and cool neon light from outside the window. Raindrops continuously slide slowly down the window in the background, with slight steam rising from the coffee on the table. The character blends naturally with the scene edges, with no cutout artifacts. \[Camera and quality] 15-second long take, camera pushes forward extremely slowly, extremely stable frame, cinematic lighting, 8K resolution, photorealistic quality.	Reference image Reference video Reference audio

Capability	Input prompt	Input materials	Output video
Reference file - PPT to video	A high-end smart glasses product advertisement, with an overall minimalist, futuristic, fashion-forward style, restrained lighting, a palette of black, silver-gray, and ice-blue as main tones, with localized soft white light accents and parameter UI graphics. > See full prompt in the collapsible section below the table.	[glass.pptx](https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260825/msmbpl/glass.pptx)
Reference file - Excel to video	Total duration 22 seconds, 4 segments joined in sequence. Pure white background throughout, soft color blocks and clean line charts, Apple Keynote-style minimalist business aesthetic, sans-serif dark gray font. > See full prompt in the collapsible section below the table.	[H1-2026跨境电商月度GMV.xlsx](https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260825/lepucv/H1-2026%E8%B7%A8%E5%A2%83%E7%94%B5%E5%95%86%E6%9C%88%E5%BA%A6GMV.xlsx)

Capability	Input prompt	Input reference video	Output video
Style conversion	Convert the entire scene to clay style
Dialogue editing	Edit the video, change the man's dialogue to: "The deal is done. Now\... we disappear."
Reference editing	Edit the video: the woman in Video 1 puts on the hat from Image 1, naturally fitting her head shape. The man in Video 1 puts on the hat from Image 2, naturally fitting his head shape. The man's russet-brown shirt is replaced with the blue washed loose denim shirt from Image 3, with the collar open and sleeves rolled up to the forearms. The movements, other clothing, and the rest of the scene remain unchanged.	Reference video Reference images (3)

type	Description	Constraints
`first\_frame`	First frame image, strictly used as the first frame of the video	Maximum 1
`last\_frame`	Last frame image, strictly used as the last frame of the video	Maximum 1
`reference\_image`	Reference image	Maximum 10
`reference\_video`	Reference video	Maximum 5, total duration no more than 15 seconds, frame rate ≥16 fps
`reference\_audio`	Reference audio	Maximum 5, total duration no more than 15 seconds
`file`	File (docx, doc, xlsx, xls, pptx, ppt, pdf, txt, md)	Maximum 1, cannot be used with link simultaneously
`link`	Web link (public web pages)	Maximum 1, cannot be used with file simultaneously

`voice` parameter	Details	Supported languages
`Tina`	Voice name: Tina Description: A voice like a warm cup of cocoa—sweet and cozy, yet sharp when solving problems	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Cindy`	Voice name: Cindy Description: A sweet-talking young woman from Taiwan	Chinese (Taiwanese accent), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Liora Mira`	Voice name: Liora Mira Description: A gentle voice that weaves warmth into everyday life	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Raymond`	Voice name: Raymond Description: A clear-voiced, takeout-loving homebody	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Zane`	Voice name: Zane Description: Magnetic and charming.
`Katerina`	Voice name: Katerina Description: A mature, commanding voice with rich rhythm and resonance	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Ryan`	Voice name: Ryan Description: High-energy delivery with strong dramatic presence—realism meets intensity	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Mia`	Voice name: Mia Description: A lifestyle artist who shares slow-living aesthetics and daily comfort through a soothing voice	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Cici`	Voice name: Cici Description: A lively, sweet girl-next-door voice with a soft tone.
`Theo Calm`	Voice name: Theo Calm Description: Conveys understanding in silence and healing through words	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Serena`	Voice name: Serena Description: A gentle young woman	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Maia`	Voice name: Maia	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Evan`	Voice name: Evan	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Qiao`	Voice name: Qiao Description: Not just cute—she’s sweet on the surface and full of personality underneath	Chinese (Taiwanese accent), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Momo`	Voice name: Momo Description: Playful and mischievous—here to cheer you up	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Wil`	Voice name: Wil Description: A young man from Shenzhen who speaks with a Hong Kong–Taiwan accent	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Angel`	Voice name: Angel Description: Slightly Taiwanese-accented—and very sweet	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Li Cassian`	Voice name: Li Cassian Description: Speaks with restraint—three parts silence, seven parts reading the room	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Joyner`	Voice name: Joyner Description: Funny, exaggerated, and down-to-earth	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Gold`	Voice name: Gold Description: A West Coast Black rapper	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Jennifer`	Voice name: Jennifer Description: A premium, cinematic-quality American female voice	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Aiden`	Voice name: Aiden Description: An American young man skilled in cooking	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Mione`	Voice name: Mione Description: A mature, intelligent British neighbor girl	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Sunny`	Voice name: Sichuan–Sunny Description: A sweet Sichuan girl who warms your heart	Chinese (Sichuan dialect), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Dylan`	Voice name: Beijing–Dylan Description: A youth raised in Beijing’s hutongs	Chinese (Beijing dialect), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Eric`	Voice name: Sichuan–Eric Description: A lively Chengdu man from Sichuan	Chinese (Sichuan dialect), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Peter`	Voice name: Tianjin–Peter Description: A Tianjin-style xiangsheng performer—professional foil	Chinese (Tianjin dialect), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Joseph Chen`	Voice name: Joseph Chen Description: A longtime overseas Chinese from Southeast Asia with a warm, nostalgic voice	Chinese (Hokkien), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Marcus`	Voice name: Shaanxi–Marcus Description: Broad face, few words, sincere heart, deep voice—the true flavor of Shaanxi	Chinese (Shaanxi dialect), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Li`	Voice name: Nanjing–Li Description: A grumpy uncle	Chinese (Nanjing dialect), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Rocky`	Voice name: Cantonese–Rocky Description: A witty and humorous online chat companion	Chinese (Cantonese), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
Kiki	Voice name: Cantonese–Kiki Description: A sweet Cantonese girlfriend-next-door	Chinese (Cantonese), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Sohee`	Voice name: Sohee Description: A warm, cheerful, emotionally expressive Korean unnie	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Eliška`	Voice name: Eliška Description: Every word carries Central European craftsmanship and warmth	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Alek`	Voice name: Alek Description: Cold like the Russian spirit—yet warm as wool beneath a coat	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Arda`	Voice name: Arda Description: Neither high nor low—clean, crisp, and gently warm	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Dolce`	Voice name: Dolce Description: A laid-back Italian man	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Lenn`	Voice name: Lenn Description: Rational at core, rebellious in detail—a German youth who wears suits and listens to post-punk	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Ono Anna`	Voice name: Ono Anna Description: A clever, playful childhood friend	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Sonrisa`	Voice name: Sonrisa Description: A warm, outgoing Latin American woman	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Bodega`	Voice name: Bodega Description: A warm, enthusiastic Spanish man	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Andre`	Voice name: Andre Description: A magnetic, natural, and steady male voice	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Radio Gol`	Voice name: Radio Gol Description: A passionate football commentator who narrates games with poetic flair	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Rizky`	Voice name: Rizky Description: A young Indonesian man with a distinctive voice	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Roya`	Voice name: Roya Description: A sporty girl with a free-spirited heart	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Hana`	Voice name: Hana Description: A mature Vietnamese woman who loves dogs	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Jakub`	Voice name: Jakub Description: A charismatic, artistic young man from a Polish town	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Griet`	Voice name: Griet Description: A mature, artistic Dutch woman	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Marina`	Voice name: Marina Description: A girl raised in a multicultural city	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Siiri`	Voice name: Siiri Description: Reserved and gentle—with a calm, lake-like speaking pace	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Ingrid`	Voice name: Ingrid Description: A woman from rural Norway	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Sigga`	Voice name: Sigga Description: An intellectual young woman from an Icelandic town	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Bea`	Voice name: Bea Description: A sweet Filipino woman who loves coffee	Chinese (Mandarin), English French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Chloe`	Voice name: Chloe Description: A Malaysian office worker	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`Emilien`	Voice name: Emilien Description: A romantic French big brother	Chinese (Mandarin), English, French, German, Russian, Italian, Spanish, Portuguese, Japanese, Korean, Thai, Indonesian, Arabic, Vietnamese, Turkish, Finnish, Polish, Hindi, Dutch, Czech, Urdu, Tagalog, Swedish, Danish, Hebrew, Icelandic, Malay, Norwegian, Persian
`longanlingxin`	Voice name: Long An Ling Xin Description: Warm and empathetic.

Supported models	TPM rate limit tiers
qwen3.8-max	2,000,000	5,000,000	10,000,000
qwen3.8-max-0902	1,500,000	1,500,000	1,500,000
qwen3.8-flash	2,500,000	5,000,000	10,000,000
kimi-k3	1,200,000	5,000,000	10,000,000
qwen3.8-27b	5,000,000	5,000,000	5,000,000
qwen3.8-2.4t-a95b	5,000,000	5,000,000	5,000,000
qwen3.8-omni-flash	2,000,000	5,000,000	10,000,000
deepseek-v4-pro-0813	1,200,000	5,000,000	10,000,000
glm-5.3	5,000,000	5,000,000	5,000,000

Credential	Used by	Purpose	Validity
Primary API Key	Server only	Calls all Open APIs (manage worlds, exchange for tickets, generate temporary API Keys, query artifacts)	Long-lived
Temporary API Key (also called `token` in the SDK)	Client SDK	HTTP-layer authentication for the SDK (injected via `updateToken`); simply fetch and inject again after expiration	Default 1 minute, up to 30 minutes (configured via `expire\_in\_seconds`); must be renewed
ticket	Client SDK	Single-use credential for entering the room; exchanged on the server and delivered to the client	30 minutes, single-use

Item	Requirement
minSdk	24 (Android 7.0) and above
compileSdk	36
JDK	JDK 11 bytecode target (host toolchain: JDK 11 or above recommended)
Language	Kotlin (coroutine `suspend` API)
ABI	`arm64-v8a` / `armeabi-v7a` (the real-time communication engine contains native libraries)
Network	Public internet access required

Item	Notes
SDK version	`HappyOyster.VERSION`
Session `travelId`	the `encryptedTravelId` of the failing session (see 15.2)
Time of occurrence	the approximate time (minute-level is fine)
Error code	the captured `SDKError.code` (meanings in the API Reference error-code table)
Reproduction steps	action path + expected result + actual result
Environment	device model, Android version, network (WiFi/cellular)
Log file	the `HappyOysterSDK` log from 15.3 (`DEBUG`/`VERBOSE` recommended)

Concept	Description
World	An AI world, containing characters and scenes. Created and managed by your server.
Travel	A single real-time experience. Basic lifecycle: `init → pending → running → completed` (failure is `failed`). In directing and Acting modes, if the experience supports pausing, `running` can enter `paused` via `pauseTravel`, then return to `running` via `resumeTravel` (directing can additionally use `rewindTravel`, after which the server resumes the experience automatically); `running ⇄ paused` can loop multiple times.
Mode	`adventure` (device/command interaction), `directing` (text-driven narrative), or `acting` (Acting: text-driven narrative whose playback aspect ratio is fixed by the server at world creation). The SDK uniformly exposes these three values.
Real-time video	Established and maintained automatically by the SDK after `startTravel` succeeds; you do not need to connect/disconnect manually. It is released automatically on `endTravel`.

Method	Description
`initialize(context, config)`	Initializes the SDK. Idle re-initialization is supported; re-initialization while a Travel is starting, active, or ending is rejected with `103004`.
`updateToken(token)`	Injects/updates the QwenCloud gateway API Key (Bearer token).
`startTravel(ticket)`	Starts an experience with a one-time credential and automatically establishes the real-time video connection.
`pauseTravel()`	Asynchronously pauses the experience (directing and Acting, and only if the experience supports pausing); after acceptance, the actual pause is determined by `onStatusChanged(Paused)`.
`resumeTravel()`	Resumes a paused experience (directing and Acting); includes 3× retry backoff internally.
`rewindTravel(rewindToSec)`	Rewinds to the specified number of seconds (directing only, state `paused`). The seconds value must be a multiple of 4. Acting does not support rewind.
`sendInstruct(content)`	Sends a text instruction to drive the narrative (directing and Acting, `running` or `paused`).
`sendCommand(command)`	Sends direction/view/action control commands (adventure mode, `running` only; main thread). Not available for Acting.
`attachVideo()`	Returns a `SurfaceView` for playback; add it to your layout to render (main thread).
`endTravel()`	Ends the experience, automatically disconnecting the real-time connection and releasing all session resources.
`VERSION`	SDK version string (SemVer), a compile-time constant.

Event	Description
`onStatusChanged(status)`	Experience status change (including the real-time video lifecycle); values are defined in `TravelStatusValue`.
`onError(error)`	Callback when an internal automatic flow fails; a fatal error also terminates the current experience.

Type	Description
`SDKConfig`	SDK initialization configuration (`apiHost` and `model` are required, plus `logLevel`, `logcatEnabled`, `logHandler`, and `callbackTimeoutMs`).
`TravelStatusValue`	Experience status: `Init` / `Pending` / `Running` / `Paused` / `Failed` / `Completed`.
`ModeValue`	Experience mode: `adventure` / `directing` / `acting`.
`CreationModelValue`	World creation model: `Simple` (default, instruct-driven) / `ScriptList` (structured script, `sendInstruct` not supported).
`StartTravelData`	Returned by `startTravel`; contains metadata such as `mode`, `version`, `creationModel`, `aspectRatio`, and `maxExperienceTimeSec`.
`AdventureCommand`	Parameter for `sendCommand`; contains the three fields `translation` / `rotation` / `interaction`.
`SDKError`	SDK error; contains `code: Int` and optional `raw: Any?`.

Field	Type	Required	Description
`context`	`Context`	Yes	Passing `applicationContext` is recommended.
`config`	`SDKConfig`	Yes	SDK configuration; must carry the required, default-free `apiHost` and `model`.

code	Description
`100002`	`model` is blank. Initialization fails synchronously with `SDKError.raw` set to `SDKConfig.model must not be blank`; no runtime is created or replaced and no network request is made.
`103004`	Re-initialization rejected because a Travel is starting, active, or ending. Await `endTravel()` and retry.

Field	Type	Required	Description
`ticket`	`String`	Yes	The one-time experience credential, delivered by your server.
`maxExperienceTimeSec`	`Int?`	No	Maximum duration of this experience in seconds; the world ends the session automatically once it is reached. Applies to world-exploration (adventure) mode only; ignored in directing (real-time directing) and Acting modes. The allowed values are server-configured, currently `60` / `90` / `120`; passing `null` (or using the overload without this parameter) applies the server default (currently `60`). Passing an unsupported value makes the server reject `startTravel` with `400000`, throwing `SDKError(400000)` with no active Travel created. The SDK does not validate the value locally — the allowed set is authoritative on the server.

code	Description
`401010`	`ticket` invalid or expired
`401011`	`ticket` already used
`400000`	Invalid parameter (e.g. `maxExperienceTimeSec` not within the server-allowed set); this `startTravel` fails to start
`403002`	World not in a ready state
`500001`	Resource allocation / internal service failure
`103004`	A Travel is already starting, active, or ending, or `startTravel` is called concurrently (only one Travel is allowed at a time; `SDKError.raw` contains only a redacted summary of the active ticket)

code	Description
`103001`	No active experience
`103002`	State not allowed, or this experience does not support pause / resume
`103003`	Called in adventure mode; only directing and Acting support pause / resume

code	Description
`103001`	No active experience (never called `startTravel`, or it has ended)
`103003`	Current mode is neither directing nor Acting (called in adventure mode)
`103002`	The experience state is neither `running` nor `paused` (e.g., still in the `init`/`pending` phase); or the current world is in ScriptList mode (`StartTravelData.creationModel == CreationModelValue.ScriptList`)—sending instruct is not allowed in ScriptList mode, where scripts are managed by the QwenCloud platform API
`403004`	Content moderation block
`404000`	Travel does not exist

Field	Semantics	Values
`translation`	Movement: forward/left/back/right/diagonal/idle	`W` / `A` / `S` / `D` / `W\_A` / `W\_D` / `S\_A` / `S\_D` / `None`
`rotation`	View: up/down/left/right/diagonal/none	`Mouse\_Up` / `Mouse\_Down` / `Mouse\_Left` / `Mouse\_Right` / `Mouse\_Up\_Left` / `Mouse\_Up\_Right` / `Mouse\_Down\_Left` / `Mouse\_Down\_Right` / `None`
`interaction`	Interaction: jump/attack/squat/sprint/none	`Jump` / `Attack` / `Squat` / `Sprint` / `None`

Event	Description
`onStatusChanged`	Experience status change (including the real-time video lifecycle); values are defined in `TravelStatusValue`.
`onError`	Callback when an internal automatic flow fails; a fatal error also terminates the current experience (see the error-code section).

code	Meaning	Suggested handling
`400000`	Invalid parameter (invalid enum, etc.)	Check the request parameters or the SDK version
`401010`	`ticket` invalid or expired	Have your server re-issue a credential
`401011`	`ticket` already used	The credential is one-time; re-issue it
`403001`	World does not exist, has been deleted, or does not belong to the current developer (including a world already deleted within the `startTravel` credential)	Reselect a valid World
`403002`	World not in a ready state	Wait until the world is ready before starting
`403004`	Input content violation (content moderation); applies to `sendInstruct` text instructions	Modify the input content and retry
`403007`	Service specification not enabled for this account	Do not retry as capacity-full; switch to an enabled spec or request enablement
`403008`	Capacity configuration temporarily unavailable	Retry later
`404000`	Travel resource does not exist or the ID does not belong to the current account	Restart the Travel
`409000`	Request conflicts with the current resource state	Check the Travel state
`429001`	SKU concurrency limit reached	Retry after an existing session ends (do not confuse with `500001`)
`429002`	No capacity currently available	Retry later
`500001`	Inference resource allocation / internal service failure	Retry later
`500000`	Internal system error	Retry later / report

Developer quickstart

code	Meaning	Fatal?	Suggested handling
`100001`	Called before the SDK was initialized	Call rejected	`initialize` first
`100002`	`model` was blank during SDK initialization; thrown synchronously with `SDKError.raw` set to `SDKConfig.model must not be blank`; no runtime is created or replaced and no network request is made	Initialization failed	Pass a non-blank complete model name and version, then call `initialize` again; refer to the official QwenCloud HappyOyster model documentation for available values
`101001`	QwenCloud gateway API Key not injected	No	Retry after `updateToken`
`101002`	QwenCloud gateway Bearer API Key expired or rejected. Note: this is the gateway Bearer Key, not the one-time ticket; ticket-level credential errors are identified by six-digit server codes (e.g., `401010`/`401011`)	No	Re-obtain the Bearer Key and `updateToken`; no need to exchange for a new ticket
`103001`	No active experience currently	Call rejected	`startTravel` first
`103002`	The current state does not allow this operation (including: state mismatch; the experience does not support pause / resume / rewind for `pauseTravel`/`resumeTravel`/`rewindTravel` (its `version` is not the v2 identifier its mode requires); state not `paused` for `rewindTravel`; `creationModel == ScriptList` for `sendInstruct`)	Call rejected	Check the experience state and mode; `sendInstruct` is unavailable in ScriptList mode (`creationModel == CreationModelValue.ScriptList`), where script content is not managed through this SDK
`103003`	Mode mismatch: `sendCommand` called in directing or Acting, or `pauseTravel` / `resumeTravel` / `rewindTravel` / `sendInstruct` called in adventure, or `rewindTravel` called in Acting	Call rejected	Check whether the current mode matches the interface's requirement
`103004`	A concurrent `startTravel` call, or re-initialization while a Travel is starting, active, or ending (only one Travel is allowed at a time; `SDKError.raw` for concurrent start contains only a redacted ticket summary)	Call rejected	Await `endTravel()` before retrying
`105001`	Real-time connection failed	Yes	End and restart
`105002`	Real-time join timed out	Yes	End and restart
`105003`	Timed out waiting for the video first frame	Yes	End and restart
`105004`	Real-time channel not ready / send failed	No	Confirm the real-time channel is ready and retry `sendCommand` after `running`; if a specific device misbehaves, try declaring and granting `RECORD\_AUDIO` (see [Happy Oyster Android SDK Integration Guide](/api-reference/world-model/happyoyster-android-sdk-integration-guide) § Installation · Permissions)
`105005`	An SDK gateway HTTP signaling call did not return within `callbackTimeoutMs` (default 30s); RTC join and first-frame timeouts use `105002` and `105003`, respectively	No	Retrying is recommended, or increase `callbackTimeoutMs`
`105006`	Auto-end on no stream: the first frame never arrived, or the stream was interrupted during running and did not recover before timeout. The SDK proactively ends the current experience	Yes	End and restart
`106001`	Local network error	No	Retryable
`106002`	Response parsing failed	No	Thrown to the caller when triggered by an explicit call; on internal status polling, only `onError` is emitted and the experience is not terminated
`106003`	The upstream service returned an unrecognizable error response; the SDK has kept the original information in `SDKError.raw` (including gateway edge rejections such as `AccessDenied`)	No	Retryable; if it persists, investigate service availability together with `raw`. If `raw` contains `AccessDenied` (most often on the first request after initialization), this is a gateway configuration issue; check in order: ① whether the `model` name and version are correct, still available, published, and authorized; ② `apiHost` spelling; ③ whether `apiHost`, `model`, and the Key injected via `updateToken` match the required account; ④ whether your account has been added to the app allowlist
`108001`	SDK remotely disabled (fully shut down or version too low); the reason is in `SDKError.raw` (String)	Yes (when the SDK detects a disable result, it automatically ends the in-progress experience; you can restart after recovery)	Prompt the user based on the reason in `raw`; guide an upgrade when the version is too low

Item	Details
Version	International (overseas)
Sign-in	Email address + verification code
Installation package	[Happy Oyster Android Playground APK.apk](https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260717/blcjmn/Happy+Oyster+Android+Playground+APK.apk)
Network	Stable access to Happy Oyster services
Device	Android 8.0 or later on a physical device (live visuals are best experienced on a real device)

Step	Action	What you experience
① Browse content	Scroll down Home: discover shorts, featured worlds, recommended journeys	Content recommendations and cover presentation
② World library	In Gallery, switch between All / Wander / Story (i.e. world-exploration / directing) and open a world you are interested in	Browsing and filtering different types of worlds
③ Video playback	Tap a card with a video preview to enter playback	Short videos / journey replays
④ Enter a world in real time	Tap Explore to enter a world (choose adventure mode (adventure) or directing mode (directing))	Real-time visuals, session timing, and the end flow
⑤ World-exploration interaction	In adventure mode, use the joystick, view, and action buttons	Real-time control in a virtual world
⑥ Create a world	Create → upload reference images and fill in a description → submit	The complete flow from materials to an experienceable world
⑦ Personal center	Profile → view My videos / My worlds	Your history and self-created content

Item	Requirement
Minimum OS	iOS 15.0+
Language	Swift (`async/await`)
Threading	Public APIs are `@MainActor`; call them on the main thread
Import	`import HappyOysterSDK` (aggregate entry point, already `@\_exported` Core + World)

Credential	Source	Purpose	How to Inject
HTTP auth token	Your app fetches it from your own backend	General authentication for SDK calls to the gateway (long-lived, needs renewal)	`updateToken(\_:)`; the SDK keeps only the latest one
One-time ticket	Issued by your server after exchanging via the Travel credential API	Used for a single experience, invalidated immediately after use	Passed as the `createTravel(ticket:)` argument

Concept	Description
token	HTTP auth token (QwenCloud temporary API Key). Your server exchanges it via the QwenCloud API and delivers it down; it is injected through `updateToken(\_:)`, and the SDK carries it as an HTTP Bearer when requesting the gateway. The SDK keeps only the latest one, does not persist or refresh it; after it expires, you re-exchange and re-inject it.
ticket	One-time trial credential. Your server exchanges it via the open platform `get-travel-credential` (prefix `tk\_`, valid for 30 minutes, single-use), used as the `createTravel(ticket:)` argument; it becomes invalid once the experience ends or expires, and cannot be reused.
World	An AI world, containing characters and scenes. Created and managed by your server; the SDK is not involved.
Travel	A single real-time experience, corresponding to one `OysterTravel` handle. Single-use; invalidated once a terminal state is reached, requiring a fresh `createTravel` via the engine.
Session status	`OysterTravelStatus`: `idle → prepare → running → pausing → paused` (paused returns to `prepare → running` via reconnect), plus two terminal states `ended` / `failed` (see §7).
Mode	`adventure` (direction/view/action commands), `directing` (text-driven storyline), or `acting` (text-driven character performance). The `mode` returned by `start()` determines the UI accordingly; see §2 for what each mode supports.

Capability	`adventure`	`directing`	`acting`
`sendCommand` (direction/view/action)	Yes	No	No
`sendInstruct` (text instruction)	No	Yes	Yes
`pause()` / `resume()`	No	Yes	Yes
`rewind(toSec:)`	No	Yes	No — hide the entry point
`end()`	Yes	Yes	Yes
`start(maxExperienceTimeSec:)`	Applied	Ignored	Ignored

Method / Property	Description
`initialize(config:)`	Initialize the runtime and automatically register the real-time engine (once, before `createTravel`)
`updateToken(\_:)`	Inject / update the HTTP auth token
`createTravel(ticket:)`	Create a session handle with a one-time credential
`cleanup()`	Release resources (can `initialize` again)
`version`	The current SDK version

Method / Property	Description
`videoView` / `OysterVideoView(travel:)`	Playback view (UIKit / SwiftUI)
`events` / `status`	Status-change + error push stream / observable current status
`start()` / `start(maxExperienceTimeSec:)`	Connect and play (optionally request the maximum duration of an adventure experience)
`sendInstruct(content:)`	Directing-mode text instruction
`sendCommand(\_:)` / `flushCommands()`	Adventure-mode control
`pause()` / `resume()`	Pause / resume (`directing` and `acting`)
`rewind(toSec:)`	Rewind (paused only)
`end()`	End (idempotent, be sure to call it)
`pauseLocalAudioCapture()` / `resumeLocalAudioCapture()`	Temporarily yield / restore the microphone

Item	Requirement
Minimum OS	iOS 15.0+ (all public types are marked `@available(iOS 15.0, \*)`)
Language	Swift (`async/await`)
Concurrency	Main-thread access (entry types are marked `@MainActor`)
Network	Public network access required
Permissions	`Info.plist` must include `NSMicrophoneUsageDescription` (see below)