File Q&A

After uploading files in an Agent Application , you can ask intelligent questions about their content. This feature supports content understanding, information extraction, and intelligent Q&A for documents, images, audio, and video files, offering three processing modes. Choose the mode that best fits your needs:

Processing Mode	Description	Best For	Characteristics
Full-text citation	An internal parser extracts the file content. The full content—within the model's context length limit—is passed to the model as a single input.	Tasks requiring global understanding, such as document summarization, full-text translation, or style refinement.	Simple and direct, but limited by the model's context length.
Chunked retrieval (RAG)	An internal parser extracts the file content and splits it into smaller chunks. When you ask a question, the system retrieves the most relevant chunks and passes them—and your question—to the model to generate an answer.	Long-document Q&A, knowledge base search, or scenarios where precise source attribution is required.	Handles very long files. Answer quality depends on chunking and retrieval strategy.
Custom processing	You provide the file (as a URL or raw content) to the model. The model then decides whether to call external tools—such as plugins or MCP Server—to process the file based on the task requirements.	Tasks requiring additional file operations, such as image style transfer or generating reports after video analysis.	Powerful and flexible, and depends on the configured tools (such as plugins and MCP).

These modes describe processing behavior at the API level. In the current console, the behavior is configured through the Pre-parse Files toggle in the Planning section and the knowledge base association. For the mapping, see How to use.

How It Works

The File Q&A capability in Agent Applications operates through the following workflow:

1. File Parsing: The system automatically detects and parses uploaded files—including documents, images, audio, and video—extracting text, visual, or audio information. The built-in parser focuses exclusively on extracting plain-text content from supported file formats.
2. Content Processing: Parsed content is handled according to the application's file handling configuration, that is, the Pre-parse Files toggle and the knowledge base association. In retrieval scenarios, the parsed result is planned and retrieved together with the user intent and the knowledge base content. When Pre-parse Files is turned on, the parser extracts the file content and passes it to the agent for replies. Content that exceeds the limit is automatically truncated.
3. Intelligent Q&A: The large language model synthesizes answers using both the file content and the user's question—delivering accurate, context-aware responses.

Scope

Supported regions

This documentation applies only to the China (Beijing) region.

Supported models

Text document Q&A has no special model requirement. To process visual files such as images, select a multimodal model such as the Qwen VL series. For image processing options, see Image processing settings for specific models.

Text generation models

• Qwen-Max, Qwen-Plus, Qwen-Turbo, Qwen-Long
• Qwen3-Coder-Plus
• Qwen3 open-source models, Qwen2.5 open-source models, Qwen2 open-source models
• Qwen-QwQ, Qwen-QwQ-Preview
• DeepSeek

Visual understanding models

• Qwen-VL-Max, Qwen-VL-Plus, Qwen-VL-OCR

Supported file formats

You can upload local documents, images, videos, or audio files in the following formats:

• Documents: .doc, .docx, .ppt, .pptx, .xls, .xlsx, .md, .txt, .pdf.
• Images: .png, .jpg, .jpeg, .bmp, .gif.
• Videos: .mp4, .mkv, .avi, .mov, .wmv, .webm, .flv.
• Audio: .aac, .amr, .flac, .m4a, .mp3, .mpeg, .ogg, .opus, .wav, .wma.

To process files larger than 10 MB, use the file upload API. See the API reference section.

How to use

File Q&A behavior is determined by the Pre-parse Files toggle in the Planning section of the agent application, together with the knowledge base association:

Behavior	Configuration	How it works	Best for
Full-text understanding	Pre-parse Files ON	Uploaded documents, images, videos, and audio are parsed by the built-in parser. The extracted text is provided to the model, which answers based on the full file content.	Document summarization, full-text translation, and style polishing
Retrieval Q&A	Knowledge base associated	Uploaded files participate in retrieval together with the knowledge base content. Answers are generated from the most relevant recalled chunks.	Long-document Q&A and scenarios that require precise source attribution
Custom processing	Pre-parse Files OFF	The file URL is passed through to the model, which handles it with the configured tools, such as plugins and MCP.	Image style transfer, video analysis, and other tasks that require tools

Configuration steps

1. Select a model in your agent application.
2. Set the Pre-parse Files toggle in the Planning section as needed. When it is turned on, file content is parsed and passed to the model. When it is turned off, file URLs are passed through.
3. (Optional) To mix file and knowledge base Q&A, associate a knowledge base in the Knowledge Base module. See Agent Application (Agent 2.0) or Agent Application (Agent 1.0).
4. (Optional, custom processing) Add the required tools under Tools. The Tools section provides built-in tools, Connector, application components, and MCP services. Plugins must be converted to MCP services before they can be added.

Upload a file and chat

Click the upload icon next to the input box in the test chat panel on the right to upload a local file, and then ask questions about its content.

Example 1: Full-text understanding

Upload Alibaba Cloud Model Studio phone product introduction.docx and ask: "Please summarize this file."

The assistant returns a summary: the document introduces six smartphone models under the Model Studio, Tongyi, and Stardust brands, with a product overview table listing the model, highlights, display, and storage or memory.

Example 2: Retrieval limited to the uploaded file

Upload Alibaba Cloud Model Studio phone product introduction.docx and ask: "Recommend a phone around CNY 5,000."

The system performs knowledge retrieval on the uploaded file and returns 4 results with scores of 0.99, 0.47, 0.46, and 0.44. Based on the retrieved content, the assistant recommends a phone (for example, "Alibaba Cloud Model Studio X1", priced at CNY 4,599 to 4,999) with highlights covering the display, performance, battery life, and camera.

Example 3: Mixed retrieval across a file and a knowledge base

First store a video file in the knowledge base. Then click the upload icon next to the input box to upload test.mp4 and ask: "Does the person in this video appear in the knowledge base?"

The system performs knowledge retrieval and returns two results. After comparison, the assistant determines that the real person in the video does not match the anime-style illustration characters in the knowledge base, and replies that the person in the video does not appear in the knowledge base.

Image processing settings for specific models

After you select a Qwen VL series model and upload an image, you can configure how the image is processed:

• Model processing: The model analyzes the image with its own vision capability and answers directly, without calling external tools. This mode suits look-and-answer scenarios.
• Model processing + planning: After understanding the image, the model determines whether to call the configured external tools, such as plugins, to complete more complex tasks. This mode suits scenarios that require editing, transforming, or tool-assisted analysis of images.

For other file types, such as documents, audio, and video, the model determines autonomously whether to invoke tools.

Example 4: Custom processing

Agent configuration:

1. Select a Qwen VL series model and set the image processing mode to Model processing + planning.
2. Add the portrait style transfer tool under Tools.

Usage: Upload the sample file girl.png and ask: "Convert this image to a vibrant cartoon style."

The agent invokes the MCP: bailian_image_style_repaint tool and converts the uploaded portrait into a vibrant cartoon-style image.

API reference

Prerequisites

1. Application publishing: You must publish your application in the console before you can call the API.
2. Processing behavior: Files are processed using the configuration that is saved in your agent application, that is, the Pre-parse Files toggle and the knowledge base association. You cannot change the behavior dynamically during API calls.

Call limits

File Q&A API calls follow the unified rate-limiting policy of the associated agent application.

• Per application: The default rate limit is 100 QPS (requests per second), counted by application ID (app_id). This limit covers all API requests to the application, including File Q&A calls.
• Per account: The default rate limit is 15,000 QPM (requests per minute), covering all API requests of all applications under the same Alibaba Cloud account.
• Requests that exceed the limits are rejected with HTTP 429 and the error code Throttling.RateQuota, and usually recover within one minute. For more information, see Error codes.

File delivery methods and parameters

File delivery method	API parameter	Main use case / key traits
Pass image URLs via the image_list parameter	image_list	For image retrieval and visual understanding. Max file size: 10 MB.
Pass generic file URLs via the file_list parameter	file_list	Passes generic file URLs. When Pre-parse Files is turned on or a knowledge base is associated, the system extracts and uses the file's text. When Pre-parse Files is turned off, the model receives the raw file URL to call tools. Max file size: 10 MB.
Use the file upload API	parameters.session_file_ids	Recommended for production environments. Workflow: 1. Call the ApplyFileUploadLease and AddFile operations in turn to upload the file and get a session file ID that starts with file_session_. 2. Pass this ID through session_file_ids in the parameters object of the chat API request (sessionFileIds in the Java SDK). Benefits: Supports larger files and offers more stable transfers.

For more information, see File Q&A (documents, images, audio, video).

Billing

• File upload: Uploading files is free of charge.
• Model calls: Q&A based on file content consumes input and output tokens. You are charged at the standard rate for your selected model. For more information, see the Model List. Token usage varies by mode:
  • Full-text citation: The entire file—or the truncated version—is passed as input. Input token usage is high.
  • Chunked retrieval: Only your question and the most relevant retrieved fragments are passed as input. Input token usage is typically much lower—ideal for long documents.
  • Custom processing: Token usage depends on interaction complexity—such as interpreting your instruction, calling tools, and summarizing tool results.
• Tool calls: Some tools incur fees. Pricing is available on the tool's details page.

FAQ

How do I provide a publicly accessible file URL for the API?

We recommend Object Storage Service (OSS). It provides highly available, reliable storage and enables you to easily generate public URLs.

Ensure your URL is accessible to Alibaba Cloud Model Studio services. Test it in a browser or with curl to confirm the file downloads successfully.

How long is a file valid?

• Uploaded via chat window: Valid only in the current session. Files expire if you close or refresh the page—or if the session times out.
• Uploaded via file upload API (session_file_ids): Valid only within the current session. Files expire after the session closes, with a maximum validity of 7 days. Long-term storage is not supported.
• Provided via URL (image_list, file_list): Validity depends entirely on your URL.

Why did my file upload fail?

Upload failures may result from several causes:

• File issues: Check file size and format against the supported file formats.
• Network issues: Check your network connection and connectivity to the service endpoint.
• URL issues: Confirm the URL is publicly accessible and not a temporary signed URL.
• API issues: Verify your authentication credentials and parameter formatting.
• Error messages: Read the API response body. It usually identifies the exact issue.

Why is the model's answer incomplete or inaccurate?

Possible reasons:

• Content truncation: File content was cut off due to token limits. When Pre-parse Files is turned on, the parser extracts the file content and passes it to the agent for replies. Content that exceeds the limit is automatically truncated. For very long files, associate a knowledge base and use retrieval instead.
• Vague questions: Be more specific. Clearly state what information you need so that the model better understands your intent.
• Poor retrieval: When a knowledge base is associated, inaccurate answers may stem from low-quality retrieved fragments or suboptimal chunking. Refine your question for better targeting, or adjust the retrieval settings of the knowledge base.
• Poor file quality: Parsers struggle with low-definition scans, documents with complex tables or formulas, or poorly encoded text files. Provide clear, simple source files whenever possible.

Why does my sub-business space show “Unauthorized” when selecting a model in Agent Applications?

Sub-business spaces require explicit authorization from the parent business space for specific models. Refer to the Sub-Business Space Model Authorization Guide.