All Products
Search

This Product

    Alibaba Cloud Model Studio:ApplyFileUploadLease

    Document Center

    Alibaba Cloud Model Studio:ApplyFileUploadLease

    Last Updated:Jun 16, 2026

    Request an upload lease for uploading knowledge base files or files for agent application conversational interactions.

    Operation description

    • RAM users (sub-accounts) must first obtain API permissions for Alibaba Cloud Model Studio (requires AliyunBailianDataFullAccess, which includes the sfm:ApplyFileUploadLease permission), and join a workspace before calling this API. Alibaba Cloud accounts (primary accounts) can directly call this API without authorization. We recommend that you call this API by using the latest Alibaba Cloud Model Studio SDK.

    • This API is not idempotent.

    Throttling: This API is subject to throttling if called too frequently. The frequency must not exceed 10 calls per second. If throttled, please retry later.

    Try it now

    Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

    Test

    RAM authorization

    The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

    • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

    • API: The API that you can call to perform the action.

    • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

    • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

      • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

      • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

    • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

    • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

    Action

    Access level

    Resource type

    Condition key

    Dependent action

    sfm:ApplyFileUploadLease

    none

    *全部资源

    *

    		 None None

    Request syntax

    POST /{WorkspaceId}/datacenter/category/{CategoryId} HTTP/1.1

    Path Parameters

    Parameter

    Type

    Required

    Description

    Example
    CategoryId

    string

    Yes

    When uploading files for building a knowledge base:

    • This field represents the category ID to which the uploaded file belongs, which is the CategoryId returned by the AddCategory API. You can also obtain it by clicking the ID icon next to the category name in Application Data - Files tab. You can pass in default here to use the system-created "Default Category".

    Note

    To create a new data table and upload data, use the Alibaba Cloud Model Studio console. This is not supported through the API.

    • You can simply pass in default here. The system will automatically create or match a default category. Dynamic file category APIs and console management pages will be available in the future.

    cate_cdd11b1b79a74e8bbd675c356a91ee35xxxxxxxx
    WorkspaceId

    string

    Yes

    The ID of the workspace to which the uploaded file belongs. For information about how to obtain the workspace ID, see How to use workspaces.

    llm-3z7uw7fwz0vexxxx

    Request parameters

    Parameter

    Type

    Required

    Description

    Example
    FileName

    string

    Yes

    When uploading files for building a knowledge base:

    • This field represents the name of the uploaded file. The file name must include the file format extension. Supported formats:

      • Documents (less than 150 MB): doc, docx, wps, ppt, pptx, xls, xlsx, md, txt, pdf, epub, mobi.

      • Spreadsheets (recommended within 10 MB and 100,000 rows): xls, xlsx.

      • Plain text (recommended not to exceed 10 MB): md, txt.

      • Images (less than 20 MB, shortest side > 15 px, longest side < 8192 px, aspect ratio < 50): png, jpg, jpeg, bmp, gif.

      • Audio: aac, amr, flac, flv, m4a, mp3, mpeg, ogg, opus, wav, webm, wma.

      • Video: mp4, mkv, avi, mov, wmv.

    • The file name must be 4 to 128 characters in length. For other limits, see Knowledge base quotas and limits.

    Note

    To create a new data table and upload data, use the Alibaba Cloud Model Studio console. This is not supported through the API.

    XXXX产品清单.pdf
    Md5

    string

    Yes

    The MD5 value of the uploaded file. The server will verify this field (currently not enabled). Please fill in the correct value.

    19657c391f6c70bcea63c154d8606bb3
    SizeInBytes

    string

    Yes

    The size of the uploaded file in bytes. The server will verify this field (currently not enabled). Please fill in the correct value. Valid values: 1 B to 100 MB.

    1000
    CategoryType

    string

    No

    The category type. If this parameter is not specified, the default value is UNSTRUCTURED. Valid values:

    UNSTRUCTURED: category for building knowledge base scenarios.

    SESSION_FILE: upload files for agent application conversational interactions.

    Note

    To create a new data table and upload data, use the Alibaba Cloud Model Studio console. This is not supported through the API.

    UNSTRUCTURED
    UseInternalEndpoint

    boolean

    No

    If you have enabled Alibaba Cloud Model Studio secure storage and need to generate a lease URL that is only accessible from the Alibaba Cloud internal network in the same region, you can set this parameter to true to improve security. If this parameter is not specified, the default value is false, which generates a publicly accessible lease URL.

    Note

    If you have not enabled Alibaba Cloud Model Studio secure storage, or are unsure whether you are using it, do not set this parameter to true (upload will fail).

    false

    Response elements

    Element

    Type

    Description

    Example

    object

    Schema of Response

    Code

    string

    The error code.

    DataCenter.FileTooLarge
    Data

    object

    The data returned.

    FileUploadLeaseId

    string

    The unique ID of the lease. You need to use this parameter when you call the AddFile API.

    1e6a159107384782be5e45ac4759b247.1719325231035
    Param

    object

    The HTTP request parameters for uploading the file.

    Headers

    any

    The key-value pairs to include in the HTTP request header. Both keys and values are strings.

    Note

    The returned Content-Type may be empty. Use the empty value as-is when uploading.

    "X-bailian-extra":"MTAwNTQyNjQ5NTE2OTE3OA==", "Content-Type":"application/pdf"
    Method

    string

    The HTTP method. Valid values:

    • PUT

    • POST.

    PUT
    Url

    string

    The upload URL for the file.

    Note

    This URL is a pre-signed URL. It does not support FormData uploads. Use binary upload instead.

    https://bailian-datahub-data-origin-prod.oss-cn-hangzhou.aliyuncs.com/1005426495169178/10024405/68abd1dea7b6404d8f7d7b9f7fbd332d.1716698936847.pdf?Expires=1716699536&OSSAccessKeyId=TestID&Signature=HfwPUZo4pR6DatSDym0zFKVh9Wg%3D
    Type

    string

    The upload method of the file. Valid values:

    • OSS.PreSignedURL

    • HTTP

    HTTP
    Message

    string

    The error message.

    User not authorized to operate on the specified resource
    RequestId

    string

    The request ID.

    778C0B3B-xxxx-5FC1-A947-36EDD13606AB
    Status

    string

    The status code returned.

    200
    Success

    boolean

    Indicates whether the API call is successful. Valid values:

    • true: The call is successful.

    • false: The call failed.

    true

    Examples

    Success response

    JSON format

    {
  "Code": "DataCenter.FileTooLarge",
  "Data": {
    "FileUploadLeaseId": "1e6a159107384782be5e45ac4759b247.1719325231035",
    "Param": {
      "Headers": "\"X-bailian-extra\":\"MTAwNTQyNjQ5NTE2OTE3OA==\",\n\"Content-Type\":\"application/pdf\"",
      "Method": "PUT",
      "Url": "https://bailian-datahub-data-origin-prod.oss-cn-hangzhou.aliyuncs.com/1005426495169178/10024405/68abd1dea7b6404d8f7d7b9f7fbd332d.1716698936847.pdf?Expires=1716699536&OSSAccessKeyId=TestID&Signature=HfwPUZo4pR6DatSDym0zFKVh9Wg%3D"
    },
    "Type": "HTTP"
  },
  "Message": "User not authorized to operate on the specified resource",
  "RequestId": "778C0B3B-xxxx-5FC1-A947-36EDD13606AB",
  "Status": "200",
  "Success": true
}

    Error codes

    See Error Codes for a complete list.

    Release notes

    See Release Notes for a complete list.