> ## Documentation Index > Fetch the complete documentation index at: https://docs.weryai.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit Deep Research Task > Submit a Deep Research task. Supports multi-round research sessions, file-based context input, and configurable AI agent tools. ## OpenAPI ````yaml /openapi-en.json post /v1/generation/deep_research openapi: 3.0.3 info: title: WeryAI Generation API description: > WeryAI Open API provides AI-powered image and video generation capabilities. ## Authentication All API requests require Bearer token authentication: ``` Authorization: Bearer YOUR_API_KEY ``` ## Task Status Generation tasks are processed asynchronously. After submission, you'll receive a `task_id` to query the task status and results. Task status descriptions: - `waiting` - Waiting for processing - `processing` - In progress - `succeed` - Completed successfully - `failed` - Failed ## Webhook Callback If you provide a `webhook_url`, a POST request containing the task result will be sent to that address when the task is completed. version: 1.0.0 contact: name: WeryAI Support url: https://weryai.com email: support@weryai.com servers: - url: https://api.weryai.com description: Production Server security: [] tags: - name: Image Generation description: Image generation related APIs - name: Image Tools description: Image editing and processing tool APIs - name: Video Generation description: Video generation related APIs - name: Podcast Generation description: Podcast generation related APIs - name: Chat description: Chat related APIs - name: Music Generation description: Music generation related APIs - name: Effect Template description: Effect template related APIs - name: File Upload description: File upload related APIs - name: Tasks description: Task query related APIs - name: Account description: Account related APIs - name: Video Tools description: Video processing and editing tools APIs - name: Audio Tools description: >- Audio processing and recognition tools APIs ## Voice Reference The following system voices are available for use with the `voice_id` parameter: ### English Voices | ID | Voice Name | Gender | Preview | |---|---|---|---| | 85 | Captivating Female | FEMALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/3987dd96b7ca46d94dd242cecf32663f.mp3) | | 84 | Playful Girl | FEMALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/cfdefca3904e8db50b05c35b0bbd5e45.mp3) | | 83 | Lovely Girl | FEMALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/2bea3739397fe4fb36346bf65e831d42.mp3) | | 82 | Cheerful Chloe | FEMALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/361f42d41f382276d2d64ec0e4851863.mp3) | | 81 | Wise Lady | FEMALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/df04fdbd3e78d00623b38dec086cf304.mp3) | | 75 | Southern Dude | MALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/b565f04d06b7a5f92d33f4edf8fee417.mp3) | | 74 | Lucky Robot | MALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/c663ca5b792ad462be53a429262eb974.mp3) | | 73 | Angry Pirate | MALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/dcc98bc48ce5cbc2c346878a0330acaa.mp3) | | 72 | Friendly Giant | MALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/54ba0fb660d8a7efac178ca7456a08a9.mp3) | | 71 | Man With Deep Voice | MALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/9493f3c864b5eabd18992cad528b67e5.mp3) | ### Chinese Voices | ID | Voice Name | Gender | Preview | |---|---|---|---| | 80 | Arrogant Miss | FEMALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/a84538991f639fb8b181d28af21c84eb.mp3) | | 79 | Kind-hearted Antie | FEMALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/00d27936559b4b35886c9e1060092227.mp3) | | 78 | Gentle Senior | FEMALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/ba07358a0a5027e7e74f2377137600a8.mp3) | | 77 | Intellectual Girl | FEMALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/091ae63f445f196f82571f6925ab8c5e.mp3) | | 76 | News Anchor | FEMALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/2b84f899ad50a01f3d3671ee55bed9d7.mp3) | | 70 | Stubborn Friend | MALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/18736aee7085e96d76b8755bf2ca181b.mp3) | | 69 | Reliable Executive | MALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/49e33c6f237fb98450ef2c1e1a30ec09.mp3) | | 68 | Lyrical Voice | MALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/bda4d4eb6bb331ec2e151eb3e1316bf1.mp3) | | 67 | Refreshing Young Man | MALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/f11374b6b82b1193f6429c3729420b1f.mp3) | | 66 | Pure-hearted Boy | MALE | [▶ Preview](https://static.weryai.com/growth/audio/audio/4af3a0b6c87a04ec3b5ed096f1b56572.mp3) | - name: Deep Research description: Deep Research related APIs paths: /v1/generation/deep_research: post: tags: - Deep Research summary: Submit Deep Research Task description: >- Submit a Deep Research task. Supports multi-round research sessions, file-based context input, and configurable AI agent tools. operationId: submitDeepResearch requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeepResearchRequest' examples: with_mode: summary: Use mode (async) value: mode: DEEP_RESEARCH input: >- Analyze the latest trends in AI-powered code generation tools thinking_summaries: auto collaborative_planning: true visualization: auto tools: - type: GOOGLE_SEARCH - type: FILE_SEARCH file_search_store_names: - my-corpus-store webhook_url: https://your-server.com/webhook with_model: summary: Use model (sync, result returned immediately) value: model: GEMINI_25_PRO input: >- Analyze the latest trends in AI-powered code generation tools thinking_summaries: auto visualization: auto tools: - type: GOOGLE_SEARCH responses: '200': description: Task submitted successfully content: application/json: schema: $ref: '#/components/schemas/DeepResearchResponse' examples: async_mode: summary: Async task submitted (mode) value: status: 0 desc: success message: success data: interaction_id: dr_interaction_abc123 task_id: task_abc123 status: processing sync_model: summary: Sync result returned (model) value: status: 0 desc: success message: success data: interaction_id: dr_interaction_abc123 task_id: task_abc123 status: succeed deep_research_outputs: - type: thought summary: - type: summary_text text: >- Analyzing the latest trends in AI-powered code generation... signature: sig_xyz - type: text text: |- ## AI Code Generation Trends Recent advances show... annotations: - type: url_citation start_index: 0 end_index: 30 url: https://example.com/ai-trends '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' security: - BearerAuth: [] components: schemas: DeepResearchRequest: type: object description: >- Request parameters for submitting a Deep Research task. At least one of `input` or `input_resource` must be provided. Exactly one of `mode` or `model` must be specified — they are mutually exclusive. properties: mode: type: string description: >- Research run mode. Mutually exclusive with `model` — provide one or the other, not both. enum: - DEEP_RESEARCH - DEEP_RESEARCH_MAX example: DEEP_RESEARCH model: type: string description: >- Model key for the research task. Mutually exclusive with `mode` — provide one or the other, not both. When `model` is specified, the task runs synchronously and the result is returned directly in the response `data.deep_research_outputs` field. | Model Name | Model Key | | --- | --- | | Gemini-2.5-Pro | GEMINI_25_PRO | | Gemini-2.5-Flash | GEMINI_25_FLASH | | Gemini-3.1-Flash-Lite | GEMINI_3_1_FLASH_LITE | | Gemini-3.1-Pro | GEMINI_3_1_PRO | example: GEMINI_25_PRO previous_interaction_id: type: string description: >- Interaction ID from a previous research or execution session, used to continue a multi-round conversation. example: dr_interaction_abc123 thinking_summaries: type: string description: >- Controls how the model exposes its reasoning chain. Set to `auto` to let the model decide. example: auto collaborative_planning: type: boolean description: >- When `true`, the task enters the research/planning phase before execution. example: true input: type: string description: >- Plain text input for the research task. At least one of `input` or `input_resource` must be provided. example: Analyze the latest trends in AI-powered code generation tools input_resource: type: array description: >- Structured input list supporting text, image, and document items. At least one of `input` or `input_resource` must be provided. items: $ref: '#/components/schemas/DeepResearchInput' visualization: type: string description: >- Controls whether the agent may generate charts or diagrams. Set to `auto` to let the model decide. example: auto tools: type: array description: List of agent tools to enable for this task. items: $ref: '#/components/schemas/DeepResearchTool' webhook_url: type: string format: uri description: Callback URL where results will be sent when the task completes. example: https://your-server.com/webhook caller_id: type: integer format: int64 description: Caller ID (for business association) DeepResearchResponse: type: object properties: status: type: integer description: Business status code (0 indicates success) example: 0 desc: type: string description: Status description example: success message: type: string description: Multi-language message example: success data: $ref: '#/components/schemas/DeepResearchResult' DeepResearchInput: type: object required: - type description: A single input item for a Deep Research task. properties: type: type: string description: |- Input type. | Value | Description | |---|---| | `TEXT` | Plain text content | | `IMAGE` | Image resource (provide `uri`) | | `DOCUMENT` | Document file such as PDF (provide `uri`) | enum: - TEXT - IMAGE - DOCUMENT example: TEXT text: type: string description: Text content. Used when `type` is `text`. example: Please analyze this document. uri: type: string format: uri description: Resource URL. Used when `type` is `image` or `document`. example: https://example.com/image.jpg DeepResearchTool: type: object required: - type description: Agent tool configuration for a Deep Research task. properties: type: type: string description: |- Tool type. | Value | Description | |---|---| | `GOOGLE_SEARCH` | Web search via Google | | `URL_CONTEXT` | Fetch and read webpage content | | `CODE_EXECUTION` | Execute code snippets | | `FILE_SEARCH` | Search within uploaded corpus files | | `MCP_SERVER` | Connect to an external MCP server | enum: - GOOGLE_SEARCH - URL_CONTEXT - CODE_EXECUTION - FILE_SEARCH - MCP_SERVER example: GOOGLE_SEARCH file_search_store_names: type: array items: type: string description: >- Names of corpus containers to search. Used when `type` is `FILE_SEARCH`. Provide the **container name** (returned as `name` from the Upload File to Corpus API), for example `fileSearchStores/my-store-123`. Do **not** use a document name (e.g. `fileSearchStores/my-store-123/documents/doc-456`) — that refers to an individual file, not a container. example: - fileSearchStores/my-store-123 name: type: string description: Display name of the MCP server. Used when `type` is `MCP_SERVER`. example: My MCP Server url: type: string format: uri description: URL of the MCP server. Used when `type` is `MCP_SERVER`. example: https://mcp.example.com headers: type: object additionalProperties: type: string description: >- HTTP request headers sent to the MCP server. Used when `type` is `MCP_SERVER`. example: Authorization: Bearer xxx allowed_tools: type: array items: type: string description: >- Subset of tools the MCP server is permitted to invoke. Used when `type` is `MCP_SERVER`. example: - GOOGLE_SEARCH - URL_CONTEXT - CODE_EXECUTION - FILE_SEARCH DeepResearchResult: type: object properties: interaction_id: type: string description: >- Unique interaction ID for this research session. Pass this as `previous_interaction_id` to continue the session. example: dr_interaction_abc123 task_id: type: string description: Task ID that can be used to query task status and results. example: task_abc123 status: type: string description: >- Current task status. Possible values: `waiting`, `processing`, `succeed`, `failed`. example: processing deep_research_outputs: type: array items: $ref: '#/components/schemas/DeepResearchOutput' description: >- Research result output list. Only returned synchronously when `model` is specified in the request. Each item can be of type `text` (text or image content) or `thought` (reasoning summary). ErrorResponse: type: object properties: status: type: integer description: Business status code example: 1001 desc: type: string description: Error description example: Parameter error message: type: string description: Error message example: Model does not exist DeepResearchOutput: type: object description: A single output item from a Deep Research session. properties: type: type: string description: >- Output item type: `text` for textual / image content, `thought` for internal reasoning summary. enum: - text - thought example: text text: type: string description: >- Main text content (present when `type` is `text` and the item is not an image). example: |- ## Quantum Computing Overview Quantum computing leverages quantum mechanical phenomena... annotations: type: array items: $ref: '#/components/schemas/DeepResearchAnnotation' description: Citation / reference annotations for `type=text` items. mime_type: type: string description: >- MIME type of the image (present when `type=image` and the item is an inline image, e.g. `image/png`). example: image/png image_url: type: string format: uri description: >- Publicly accessible URL for the image (present when `type=image` and the item is an inline image; the original base64 `data` field is replaced with this URL after upload). example: https://cdn.weryai.com/result/dr_chart1.png summary: type: array items: $ref: '#/components/schemas/DeepResearchSummaryItem' description: Thinking summary items (present when `type` is `thought`). signature: type: string description: Signature for the thought item (present when `type` is `thought`). example: sig_xyz DeepResearchAnnotation: type: object description: A citation or reference annotation within a Deep Research text output. properties: type: type: string description: Annotation type, e.g. `url_citation`. example: url_citation start_index: type: integer description: Start character index of the annotated range in the text. example: 0 end_index: type: integer description: End character index (exclusive) of the annotated range in the text. example: 30 url: type: string format: uri description: Source URL for the citation. example: https://en.wikipedia.org/wiki/Quantum_computing DeepResearchSummaryItem: type: object description: A single item in the thought summary of a Deep Research output. properties: type: type: string description: Summary item type, e.g. `summary_text`. example: summary_text text: type: string description: Summary text content. example: Analyzing the latest research on quantum computing... responses: BadRequest: description: Parameter error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 1001 desc: Parameter error message: Prompt cannot be empty Unauthorized: description: Authentication failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: 1002 desc: Authentication failed message: Invalid API Key securitySchemes: BearerAuth: type: http scheme: bearer description: > Authenticate using Bearer token. Get your API Key from the [WeryAI Console](https://weryai.com/api/keys). Example: `Authorization: Bearer sk-xxxxxxxxxxxxxxxx` ````