Create Knowledge Base and Import

POST

/api/v1/indices/rag/index/create_v2

cURL

curl -X POST "https://{workspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/indices/rag/index/create_v2" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-knowledge-base",
    "description": "Knowledge Base description",
    "structureType": "unstructured",
    "sinkType": "DEFAULT",
    "sourceType": "DATA_CENTER_FILE",
    "embeddingModelName": "text-embedding-v4",
    "chunkSize": 600,
    "docIds": ["file_abc123", "file_def456"],
    "dataSources": [{"sourceType": "DATA_CENTER_FILE"}]
  }'

{
  "code": "Success",
  "status_code": 200,
  "success": true,
  "message": "success",
  "data": {
    "pipelineId": "your_pipeline_id",
    "ingestionId": "ing_abc123",
    "status": "PENDING",
    "created_at": 1783657930436,
    "updated_at": 1783657930436
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "SUCCESS"
}

The file ID parameter is docIds — not file_ids or fileIds. However, the validation error message uses the internal name file_ids.

Knowledge Base type and usage scenario

knowledgeType and knowledgeScene correspond to Knowledge Base Type and Usage Scenario in step 1 of the console creation wizard. They must be supplied together or omitted together — sending only one returns knowledgeType and knowledgeScene cannot be empty. When both are omitted, the system applies defaults based on structureType. The console only offers a Usage Scenario choice for Document Search. The other three types have a fixed scenario that the console fills in automatically, but you must still send the pair explicitly when creating a Knowledge Base through the API.

knowledgeType	Console label	structureType	Available knowledgeScene
`document`	Document Search	`unstructured`	`basic_document_qa` (basic document Q&A) `visual_perception_qa` (visual understanding, rich text documents) `lite_document_qa` (express Q&A)
`table`	Data Query	`structured`	`basic_table_qa` (fixed)
`image`	Image Q&A	`unstructured`	`image_qa` (fixed)
`multimedia`	Audio and Video Search	`unstructured`	`basic_multimedia_qa` (fixed)

An incompatible knowledgeType and structureType pair returns knowledgeType and structureType do not match. A knowledgeScene that does not belong to the selected type returns knowledgeType and knowledgeScene do not match.
lite_document_qa (express Q&A) requires sinkType to be BUILT_IN. Using the default DEFAULT returns Lite Rag only supports BUILT_IN sink type.
visual_perception_qa and image_qa must specify a multimodal embedding model through multimodalEmbeddingModelName (for example qwen3-vl-embedding), otherwise the request returns invalid multi embedding model.
The document type also has a visual_document_qa (rich media answers) scenario. The API still accepts this value, but the console no longer exposes it, so avoid it for new Knowledge Bases.

Example request body for image Q&A:

{
  "name": "image-kb",
  "description": "Image Q&A Knowledge Base",
  "structureType": "unstructured",
  "knowledgeType": "image",
  "knowledgeScene": "image_qa",
  "sinkType": "BUILT_IN",
  "sourceType": "DATA_CENTER_FILE",
  "multimodalEmbeddingModelName": "qwen3-vl-embedding",
  "docIds": ["file_abc123"],
  "dataSources": [{ "sourceType": "DATA_CENTER_FILE" }]
}

Authorizations

string

header

required

DashScope API Key, obtained from the API Key page in the console.

Body

application/json

string

required

Knowledge Base name. 1-20 characters.

Required range:length: 1–20

string

required

Knowledge Base description. 1-200 characters.

Required range:length: 1–200

enum<string>

required

Structure type — unstructured or structured.

Available options:unstructured,structured

string

default"DEFAULT"

required

Storage type. Defaults to DEFAULT. BUILT_IN uses the platform's built-in vector storage and is required when knowledgeScene is lite_document_qa (express Q&A).

string

required

Data source type, for example DATA_CENTER_FILE.

string[]

required

Required. File IDs to import at creation time. Values come from the fileId returned by addFile, or query existing files via listFile. Up to 10000 files recommended. The parameter name is docIds, not file_ids or fileIds; however, the validation error message uses the internal name file_ids.

Required range:items >= 1

object[]

required

Data source configuration list.

Show child attributes

string

Data source type, for example DATA_CENTER_FILE.

enum<string>

Knowledge Base type, matching the Knowledge Base Type option in the console: document (document search), table (data query), image (image Q&A), multimedia (audio and video search). The value must be compatible with structureType: use unstructured for document, image, and multimedia, and structured for table. Must be supplied together with knowledgeScene, or omitted together with it. When both are omitted, the system applies defaults based on structureType.

Available options:document,table,image,multimedia

enum<string>

Usage scenario, matching the Usage Scenario option in the console. Valid values depend on knowledgeType: document supports basic_document_qa (basic document Q&A), visual_perception_qa (visual understanding, rich text documents), and lite_document_qa (express Q&A); table is fixed to basic_table_qa; image is fixed to image_qa; multimedia is fixed to basic_multimedia_qa. The console only offers a scenario choice for Document Search and fills in the fixed value for the other types, but you must still send it explicitly through the API. Must be supplied together with knowledgeType, or omitted together with it. Note: lite_document_qa requires sinkType to be BUILT_IN, and visual_perception_qa and image_qa require a multimodal embedding model set through multimodalEmbeddingModelName. The document type also accepts visual_document_qa (rich media answers), which the console no longer exposes.

Available options:basic_document_qa,visual_document_qa,lite_document_qa,visual_perception_qa,basic_table_qa,image_qa,basic_multimedia_qa

string

Embedding model name, for example text-embedding-v4.

string

Multimodal embedding model name, for example qwen3-vl-embedding. Required when knowledgeScene is image_qa (image Q&A) or visual_perception_qa (visual understanding). A missing or invalid value returns invalid multi embedding model.

integer

Document Chunk size, in characters. Recommended range 300-800.

Required range:x >= 1

string[]

Category ID list.

Response

200-application/json

string

Response code. Success on success.

integer

HTTP status code.

boolean

Whether the request succeeded. true on success.

string

Response message. success on success.

string

Unique request identifier. Include this ID when reporting an issue.

string

Request status. SUCCESS on success.

object

Show child attributes

string

Knowledge Base ID.

string

Import job ID.

string

Job status. PENDING immediately after creation.

integer

Knowledge Base creation time (Unix milliseconds).

integer

Knowledge Base last update time (Unix milliseconds).

​Knowledge Base type and usage scenario

Authorizations

Body

Response

Knowledge Base type and usage scenario