docs(api): add multi-file ingestion guidance to vectorstorefile/filebatch params

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 139
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-00994178cc8e20d71754b00c54b0e4f5b4128e1c1cce765e9b7d696bd8c80d33.yml
-openapi_spec_hash: 81f404053b663f987209b4fb2d08a230
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-24647ccd7356fee965aaca347476460727c6aec762e16a9eb41950d6fbccf0be.yml
+openapi_spec_hash: ef99e305f20ae8ae7b2758a205280cca
 config_hash: 5635033cdc8c930255f8b529a78de722

vectorstorefile.go

@@ -384,7 +384,9 @@ func (r *VectorStoreFileContentResponse) UnmarshalJSON(data []byte) error {
 type VectorStoreFileNewParams struct {
 	// A [File](https://platform.openai.com/docs/api-reference/files) ID that the
 	// vector store should use. Useful for tools like `file_search` that can access
-	// files.
+	// files. For multi-file ingestion, we recommend
+	// [`file_batches`](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch)
+	// to minimize per-vector-store write requests.
 	FileID string `json:"file_id" api:"required"`
 	// Set of 16 key-value pairs that can be attached to an object. This can be useful
 	// for storing additional information about the object in a structured format, and

vectorstorefilebatch.go

@@ -270,14 +270,16 @@ type VectorStoreFileBatchNewParams struct {
 	// A list of [File](https://platform.openai.com/docs/api-reference/files) IDs that
 	// the vector store should use. Useful for tools like `file_search` that can access
 	// files. If `attributes` or `chunking_strategy` are provided, they will be applied
-	// to all files in the batch. The maximum batch size is 2000 files. Mutually
-	// exclusive with `files`.
+	// to all files in the batch. The maximum batch size is 2000 files. This endpoint
+	// is recommended for multi-file ingestion and helps reduce per-vector-store write
+	// request pressure. Mutually exclusive with `files`.
 	FileIDs []string `json:"file_ids,omitzero"`
 	// A list of objects that each include a `file_id` plus optional `attributes` or
 	// `chunking_strategy`. Use this when you need to override metadata for specific
 	// files. The global `attributes` or `chunking_strategy` will be ignored and must
-	// be specified for each file. The maximum batch size is 2000 files. Mutually
-	// exclusive with `file_ids`.
+	// be specified for each file. The maximum batch size is 2000 files. This endpoint
+	// is recommended for multi-file ingestion and helps reduce per-vector-store write
+	// request pressure. Mutually exclusive with `file_ids`.
 	Files []VectorStoreFileBatchNewParamsFile `json:"files,omitzero"`
 	paramObj
 }
@@ -322,7 +324,9 @@ func (u *VectorStoreFileBatchNewParamsAttributeUnion) asAny() any {
 type VectorStoreFileBatchNewParamsFile struct {
 	// A [File](https://platform.openai.com/docs/api-reference/files) ID that the
 	// vector store should use. Useful for tools like `file_search` that can access
-	// files.
+	// files. For multi-file ingestion, we recommend
+	// [`file_batches`](https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch)
+	// to minimize per-vector-store write requests.
 	FileID string `json:"file_id" api:"required"`
 	// Set of 16 key-value pairs that can be attached to an object. This can be useful
 	// for storing additional information about the object in a structured format, and