CVAT SDK - better documentation needed

[maecky]

Actions before raising this issue

• I searched the existing issues and did not find anything similar.
• I read/searched the docs

Steps to Reproduce

I do have Azure Blob Storage connected to CVAT. All image files with corresponding manifest are located in the storage.
I could like to automate the task creation in a project with the help of the cvat_sdk. From the documentation, it is impossible for me to get that working.

First I tried it via the swagger_api documentation (and reverse engineered the browser calls). I was only able to create empty tasks there:

session = requests.session()
login_resp = session.post(LOGIN_URL, json=login_data)
cookies = login_resp.cookies
csrftoken = session.cookies['csrftoken']
header = {
    "X-CSRFToken": csrftoken
}

payload = {
        "chunk_size": None,
        "size": 0,
        "image_quality": 70,
        "start_frame": 0,
        "stop_frame": 40,
        "frame_filter": "",
        "compressed_chunk_type": "imageset",
        "original_chunk_type": "imageset",
        "client_files": [],
        "server_files": [
            "manifest.jsonl"
        ],
        "remote_files": [],
        "use_zip_chunks": False,
        "server_files_exclude": [],
        "use_cache": False,
        "copy_data": False,
        "storage_method": "file_system",
        "storage": "local",
        "sorting_method": "lexicographical",
        "filename_pattern": None,
}

header_upload = {
    "Upload-Start": "true",
}
r = session.post(f"{BASE_URL}/tasks/{id}/data?org=testorg", json=json.dumps(payload), cookies=cookies, headers=header_upload)

This request always ends in Response[500]. I tried with various combinations of Upload-Start and Upload-Finish headers but I am not able to get it working....

Then I switched to cvat-sdk high level API:

with make_client(host=BASE_URL, credentials=(USER, PASSWORD)) as client:
    client.organization_slug = "testorg"

    task_spec = {
        "name": "api_test_10",
        "project_id": 20,
        "labels": [],
        "subset": "string",
        "target_storage": {
            "location": "cloud_storage",
            "cloud_storage_id": 21
        },
        "source_storage": {
            "location": "cloud_storage",
            "cloud_storage_id": 21
        },
        "server_files": [
            "manifest.jsonl"
        ],
        "sorting_method": "lexicographical",
    }

    task = client.tasks.create_from_data(
        spec=task_spec,
        # resource_type=ResourceType.REMOTE,
        resources=['various_3.jsonl'],
    )

The result I get is:

HTTP response body: b'{"state":"Failed","message":"A manifest file can only be used with the \'use cache\' option or when \'sorting_method\' is \'predefined\'","progress":0.0}'

The documentation of the SDK is pretty hard to follow, it would be nice to have a few more examples in there.
Any help would be apprecitad. Thanks!

Expected Behavior

No response

Possible Solution

No response

Context

No response

Environment

No response

[thmegy]

I would also be very interested by the answer to this issue.
From the documentation, it is not possible to understand how to load data from the cloud storage...

[code4days]

I'm facing a similar issue, the documentation is extremely lacking, especially when it comes to cloud storage.

[sriramsowmithri9807]

I am very intrested to solve this issue, from the documentation, it is possible to me to understand how to load a certain data from a cloud platform, what the company organization is using.

[jeyasimma]

If it is not still done, could you assign it to me?

[palakm-26]

hii @maecky , is this issue still open ?
if yes, i would like to contribute on this issue.

[davyjones7321]

"Hi, I'd like to work on this! I'll add some examples to the SDK docs showing how to create tasks from cloud storage."

[AbhishekHosamani123]

Hi! I'd like to work on this issue.

I found the SDK documentation example in highlevel-api.md that currently demonstrates local file uploads only. I plan to add a cloud storage example for create_from_data() and document the required parameters such as cloud_storage_id.

[AbhishekHosamani123]

Hi! I have submitted a PR that adds a cloud storage example for create_from_data() in the SDK documentation.

PR: #10808

[Mudrikaaa]

Hey ;) I'd like to work on this. I'm planning to add a section to the SDK high-level API docs showing how to create a task from cloud storage with a manifest, including the use_cache / sorting_method="predefined" requirement that this issue runs into. Could this be assigned to me?

[AlessandroMuleo]

hi, is this issue still open ?
i would like to contribute.

[Shoutshi03]

Hi everyone,

I'd like to work on this issue.

After checking the current cvat_sdk docs, I noticed that the workflow for creating tasks linked to Cloud Storage (Azure/S3) isn't very explicit, which leads to confusion around using tasks.create_from_data() with remote manifests or cloud_storage_id.

I can add a practical code example to the SDK documentation showing how to properly set up Client and pass the required parameters for cloud-hosted resources. I'll also double-check the docstrings to make sure parameter requirements are clear, and build the docs locally to verify the rendering before opening a PR.

Could you please assign this to me if the approach sounds good to you?

Thanks!