explicit() silently drops auto_transcription parameter (not in __SIMPLE_UPLOAD_PARAMS)

[pizzacoffeecode]

Summary

The explicit() method silently drops the auto_transcription parameter because it is not included in __SIMPLE_UPLOAD_PARAMS in cloudinary/utils.py. This means calling cloudinary.uploader.explicit(public_id, type="upload", resource_type="video", auto_transcription=True) sends a request to the API without the auto_transcription field, so transcription is never triggered.

Steps to Reproduce

import cloudinary
import cloudinary.uploader

# Upload a video
upload = cloudinary.uploader.upload(
    "https://res.cloudinary.com/demo/video/upload/dog.mp4",
    resource_type="video",
    public_id="transcription_bug_test",
    type="upload",
)

# Try to trigger transcription via explicit()
result = cloudinary.uploader.explicit(
    "transcription_bug_test",
    type="upload",
    resource_type="video",
    auto_transcription=True,
)
print(result.get("info"))  # None -- no transcription triggered

Expected Behavior

The response should include:

{
  "info": {
    "auto_transcription": {
      "status": "pending",
      "data": { "mode": "create", "translate": [] }
    }
  }
}

Actual Behavior

The info key is absent from the response. The auto_transcription parameter is silently stripped by build_upload_params() because it's not in __SIMPLE_UPLOAD_PARAMS.

Proof via curl (API works correctly)

The equivalent direct API call works:

curl -X POST "https://api.cloudinary.com/v1_1/CLOUD_NAME/video/explicit" \
  -d "public_id=transcription_bug_test" \
  -d "auto_transcription=true" \
  -d "type=upload" \
  -d "timestamp=TIMESTAMP" \
  -d "api_key=API_KEY" \
  -d "signature=SIGNATURE"

This returns the expected info.auto_transcription.status: "pending" response.

Root Cause

In cloudinary/utils.py, build_upload_params() constructs the request parameters from two sources:

1. __SIMPLE_UPLOAD_PARAMS - a whitelist of parameter names copied directly from options
2. __SERIALIZED_UPLOAD_PARAMS - parameters that need special serialization

auto_transcription is in neither list, so it is dropped.

Workaround

Bypass explicit() by building params manually and calling call_cacheable_api directly:

params = cloudinary.utils.build_upload_params(type="upload", resource_type="video")
params["public_id"] = public_id
params["auto_transcription"] = "true"
params = {k: v for k, v in params.items() if v is not None}

result = cloudinary.uploader.call_cacheable_api(
    "explicit", params, type="upload", resource_type="video"
)

Suggested Fix

Add "auto_transcription" to the __SIMPLE_UPLOAD_PARAMS tuple in cloudinary/utils.py.

Environment

• pycloudinary version: 1.44.1 (latest as of 2026-04-15)
• Python: 3.13.9
• OS: Linux (Docker)

Related

The Cloudinary documentation and release notes (June 27, 2024) explicitly show auto_transcription being used with explicit(). The API supports it; only the Python SDK drops it.

[skalahasti-cloudinary]

Hi @pizzacoffeecode

Thanks for reporting this. Looking at the code, this is still pending to be implemented in the Python SDK. I will keep you posted once we release it to Prod.

Thanks,
Sree