Docs

Torch Object Storage

Vector

PutVectors

Description

Batch insert vectors into the vector index.

Request syntax

The endpoint must use the Bucket Endpoint.

POST /PutVectors HTTP/1.1​
Host: {VectorBucketName}-{AccountID}.tosvectors-cn-beijing.volces.com​
Authorization: authorization string​
Date: Mon, 10 Dec 2025 12:49:14 GMT​
​
{​
    "vectorBucketName": "test-vector-bucket",​
    "indexName":"test-index",​
    "vectors": [​
        {​
            "key": "key0",​
            "metadata": {​
                "key_a": "va",​
                "key_b": "vb",​
                "key_c": "vc"​
            },​
            "data":{​
                "float32": [0.1, 0.1, 0.1, 0.1, 0.1]​
            }​
        },​
        {​
            "key": "key1",​
            "metadata": {​
                "key_a": "va",​
                "key_b": "vb",​
                "key_c": "vc1",​
                "key_d": "vd"​
            },​
            "data":{​
                "float32": [0.2, 0.2, 0.2, 0.2, 0.2]​
            }​
        }​
    ]​
}​

Request parameters and headers

None.

Request body elements

Field name	Type	Required	Example value	Description
vectorBucketName	String	Yes	test-vector-bucket	vector bucket name.
indexName	String	Yes	test-index	vector index name.
vectors	PutInputVector[]	Yes	See the table below	Array of vectors to add to the vector index. The number of vectors in a single request cannot exceed the resource capacity (minimum 1, maximum 500); otherwise, the request will be rejected with a ServiceUnavailableException error.

PutInputVector structure parameter description:

Field name	Type	Example value	Description
data	VectorData	"float32": [0.1, 0.1, 0.1, 0.1, 0.1]	vector data. ensure the query vector dimension matches the dimension of the vector index being queried.
key	String	key0	Unique identifier of the vector.
metadata	JSON value	{ "key_a": "va", "key_b": "vb", "key_c": "vc" }	Metadata associated with the vector, a map composed of user-defined KV pairs.

The VectorData structure is a Union type with only one active member (float32); see the table below.

Field name	Type	Description
float32	float32[]	Vector data. The vector dimension must match the vector index dimension defined in CreateIndex.

Response headers

For common response headers, see Common parameters.

Response body elements

If the operation succeeds, the service returns an HTTP 200 response with an empty response body element.

If the operation fails, it returns the error code defined in Response code.

Sample request

POST /PutVectors HTTP/1.1​
Host: test-vector-bucket-1111.tosvectors-cn-beijing.volces.com​
Authorization: authorization string​
Date: Mon, 10 Dec 2025 12:49:14 GMT​
{​
    "vectorBucketName": "test-vector-bucket",​
    "indexName":"test-index",​
    "vectors": [​
        {​
            "key": "key0",​
            "metadata": {​
                "key_a": "va",​
                "key_b": "vb",​
                "key_c": "vc"​
            },​
            "data":{​
                "float32": [0.1, 0.1, 0.1, 0.1, 0.1]​
            }​
        },​
        {​
            "key": "key1",​
            "metadata": {​
                "key_a": "va",​
                "key_b": "vb",​
                "key_c": "vc1",​
                "key_d": "vd"​
            },​
            "data":{​
                "float32": [0.2, 0.2, 0.2, 0.2, 0.2]​
            }​
        }​
    ]​
}​

Sample response

HTTP/1.1 200 OK​
x-tos-id-2: 797014003c90a9b694003c9-b15a995-1vV80n-CVB-cb-tos-1az-front-azd-vectors-2 ​
x-tos-request-id: 797014003c90a9b694003c9-b15a995-1vV80n-CVB-cb-tos-1az-front-azd-vectors-2          ​
Date: Mon, 10 Dec 2025 12:49:14 GMT​
server: TosServer​
Content-Length: 0 ​

Last updated: 2026.01.04 14:21:23