Prerequisites
Configure the endpoint and authentication first. See API overview and Authentication.
Endpoint
POST /api/v1/indices/rag/index/chunk/create
Add a chunk to a specified knowledge base.
Supports document search (document), data query (table), and image Q&A (image) knowledge bases; does not support audio/video search (multimedia). Data query and image Q&A knowledge bases only support the spreadsheet connector (Excel) data source. This API is idempotent. Frequent calls will be rate-limited; do not exceed 10 calls per second.
Request body
| Field | Required | Type | Description |
|---|
pipelineId | Yes | string | Knowledge base ID, the data.id returned by the createIndex API. |
dataId | No | string | File ID, the fileId returned by the addFile API. For document-search knowledge bases, specifies the document the chunk belongs to. |
field | Yes | object | Chunk content passed as key-value pairs. The structure varies by knowledge base type. Document search (document) uses fixed keys — sub-fields: content (string, required, chunk body text, maximum length 6000), title (string, optional, chunk title, maximum length 50), image_urls (array<string>, optional, image URLs contained in the chunk, up to 10). Data query (table) and image Q&A (image) keys are not fixed; they are determined by the data source table of the knowledge base — the key is the Excel column header and the value is the corresponding column value, and column headers that participate in retrieval or replies are required. Value requirements by type: String — maximum length 6000; Time — 13-digit timestamp in milliseconds; Long — integer, maximum 2147483647; Double — decimals supported; image_url — up to 5 images, with multiple images joined into a single string using English commas. |
Request example
Document search (document) knowledge base, using fixed keys:
curl -X POST "$BASE_URL/api/v1/indices/rag/index/chunk/create" \
-H "Authorization: Bearer $BAILIAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"pipelineId": "exg5ghdkag",
"dataId": "file_2aaa9c62d6b243b5be26636fc65c279f_12326038",
"field": {
"content": "阿里云百炼 Knowledge Studio 支持多种文档格式的解析，包括 PDF、Word、PPT 等。",
"title": "文档解析与切片",
"image_urls": [
"https://example.com/images/chunk-flow.png"
]
}
}'
curl -X POST "$BASE_URL/api/v1/indices/rag/index/chunk/create" \
-H "Authorization: Bearer $BAILIAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"pipelineId": "exg5ghdkag",
"dataId": "file_xxx",
"field": {
"Product Name": "Wireless Bluetooth Headphones",
"Publish Time": 1752624000000,
"Stock Quantity": 1580,
"Unit Price": 299.99,
"image_url": "https://example.com/images/headphones-front.jpg,https://example.com/images/headphones-side.jpg"
}
}'
BASE_URL is https://{workspace_id}.cn-beijing.maas.aliyuncs.com ({workspace_id} is the workspace ID), and BAILIAN_API_KEY is your Alibaba Cloud Model Studio API key.
Response example
Returns 200 on success.
{
"code": "Success",
"status_code": 200,
"success": true,
"message": "success",
"request_id": "56b54481-d259-9ff9-93c1-712897e5d8eb",
"status": "SUCCESS"
}
Response fields
| Field | Type | Description |
|---|
code | string | Response code. Success on success. |
status_code | integer | HTTP status code. |
request_id | string | Unique request identifier. Provide this ID when troubleshooting. |
success | boolean | Whether the API call succeeded. |
message | string | Response message. success on success. |
status | string | Status returned by the API. SUCCESS on success. |
Error codes
| HTTP status code | Error code | Message | Description |
|---|
| 400 | Index.InvalidParameter | Required parameter missing or invalid. | Invalid request parameters. |
| 401 | InvalidApiKey | Invalid API-key provided. | Authentication failed. The API key is invalid or missing. |
