Documentation Index
Fetch the complete documentation index at: https://cloudinary.com/documentation/llms.txt
Use this file to discover all available pages before exploring further.
AI Video Analysis API (Beta)
Download OpenAPI DocumentUse the AI Video Analysis API to generate a visual transcription of a video: a sequence of timestamped, natural-language descriptions of what's visible on screen. You submit a stored video asset, optionally guide the analysis with a prompt, and poll the asynchronous job until the generated visual transcript file is ready. See the AI Video Analysis guide for the full workflow.
The API supports Basic Authentication using your Cloudinary API Key and API Secret (which can be found in the API Keys page of your Cloudinary Console).
Note: The AI Video Analysis API is currently in Beta. There may be minor changes to parameter names or other implementation details before the general access release. We invite you to try it out. We would appreciate any feedback via our support team.
Submits a stored video asset for visual analysis and returns a job you can poll for the result.
Body Required application/json
A JSON object with the video asset to analyze and optional analysis options.
- video_asset_id stringRequired
Cloudinary asset ID of the input video to analyze.
- visual_transcription_prompt string
A natural-language instruction that guides the description style or focus, for example
focus on describing colors. If omitted, a default prompt is used.
Responses
201 AI Video Analysis job created
- request_id stringRequired
Unique identifier of the API request, useful for support and debugging.
example"6ec0bd7f11c043da975e2a8ad9ebae0b" - data AIVideoAnalysisResponseRequired
ShowHide child attributes of data
- job_id stringRequired
Unique identifier of the analysis job, used to poll for the result.
example"550e8400e29b41d4a716446655440000" - status stringRequired
Current status of the analysis job.
example"pending"enum"pending""completed""failed" - visual_transcription AIVideoAnalysisVisualTranscriptionnullable
Details of the generated visual transcript file, stored as a raw asset in your product environment (present when the status is
completed).ShowHide child attributes of visual_transcription
- asset_id string
Cloudinary asset ID of the visual transcript file.
- public_id string
Cloudinary public ID of the visual transcript file.
- resource_type string
Cloudinary resource type of the visual transcript file.
- delivery_type string
Cloudinary delivery type of the visual transcript file.
- url string
HTTPS URL of the visual transcript file.
- message string
Error message when the analysis has failed.
400 Bad request - validation or safety error
- request_id stringRequired
Unique identifier of the API request, useful for support and debugging.
example"6ec0bd7f11c043da975e2a8ad9ebae0b" - error objectRequired
Details of the error that occurred.
ShowHide child attributes of error
- message string
Human-readable description of the error.
401 Authentication error
- request_id stringRequired
Unique identifier of the API request, useful for support and debugging.
example"6ec0bd7f11c043da975e2a8ad9ebae0b" - error objectRequired
Details of the error that occurred.
ShowHide child attributes of error
- message string
Human-readable description of the error.
500 Internal server error
- request_id stringRequired
Unique identifier of the API request, useful for support and debugging.
example"6ec0bd7f11c043da975e2a8ad9ebae0b" - error objectRequired
Details of the error that occurred.
ShowHide child attributes of error
- message string
Human-readable description of the error.
/ai_video_analysiscurl -X POST 'https://api.cloudinary.com/v2/video/CLOUD_NAME/ai_video_analysis' \
-u 'API_KEY:API_SECRET' \
-H 'Content-Type: application/json' \
-d '{
"video_asset_id": "2fb8263411604d13a5d33e7623edc750",
"visual_transcription_prompt": "focus on describing colors"
}'{
"request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
"data": {
"job_id": "550e8400e29b41d4a716446655440000",
"status": "pending"
}
}{
"request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
"error": {
"message": "string"
}
}{
"request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
"error": {
"message": "string"
}
}{
"request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
"error": {
"message": "string"
}
}Returns the current status of an analysis job. When the status is completed, the response includes the generated visual transcript file's asset details and delivery URL.
Path parameters
- jobId stringRequired
The AI Video Analysis job ID returned from the create endpoint.
Responses
200 Job status (pending, completed, or failed)
- request_id stringRequired
Unique identifier of the API request, useful for support and debugging.
example"6ec0bd7f11c043da975e2a8ad9ebae0b" - data AIVideoAnalysisResponseRequired
ShowHide child attributes of data
- job_id stringRequired
Unique identifier of the analysis job, used to poll for the result.
example"550e8400e29b41d4a716446655440000" - status stringRequired
Current status of the analysis job.
example"pending"enum"pending""completed""failed" - visual_transcription AIVideoAnalysisVisualTranscriptionnullable
Details of the generated visual transcript file, stored as a raw asset in your product environment (present when the status is
completed).ShowHide child attributes of visual_transcription
- asset_id string
Cloudinary asset ID of the visual transcript file.
- public_id string
Cloudinary public ID of the visual transcript file.
- resource_type string
Cloudinary resource type of the visual transcript file.
- delivery_type string
Cloudinary delivery type of the visual transcript file.
- url string
HTTPS URL of the visual transcript file.
- message string
Error message when the analysis has failed.
401 Authentication error
- request_id stringRequired
Unique identifier of the API request, useful for support and debugging.
example"6ec0bd7f11c043da975e2a8ad9ebae0b" - error objectRequired
Details of the error that occurred.
ShowHide child attributes of error
- message string
Human-readable description of the error.
403 Authorization error
- request_id stringRequired
Unique identifier of the API request, useful for support and debugging.
example"6ec0bd7f11c043da975e2a8ad9ebae0b" - error objectRequired
Details of the error that occurred.
ShowHide child attributes of error
- message string
Human-readable description of the error.
404 Job not found
- request_id stringRequired
Unique identifier of the API request, useful for support and debugging.
example"6ec0bd7f11c043da975e2a8ad9ebae0b" - error objectRequired
Details of the error that occurred.
ShowHide child attributes of error
- message string
Human-readable description of the error.
/ai_video_analysis/{jobId}curl 'https://api.cloudinary.com/v2/video/CLOUD_NAME/ai_video_analysis/{jobId}' \
-u 'API_KEY:API_SECRET'{
"request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
"data": {
"job_id": "550e8400e29b41d4a716446655440000",
"status": "completed",
"visual_transcription": {
"asset_id": "9f8e7d6c5b4a30291807a6b5c4d3e2f1",
"public_id": "samples/sea-turtle.visual.transcript",
"resource_type": "raw",
"delivery_type": "upload",
"url": "https://res.cloudinary.com/demo/raw/upload/v1/samples/sea-turtle.visual.transcript"
}
}
}{
"request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
"error": {
"message": "string"
}
}{
"request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
"error": {
"message": "string"
}
}{
"request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
"error": {
"message": "string"
}
}Models
Show schema
- video_asset_id stringRequired
Cloudinary asset ID of the input video to analyze.
- visual_transcription_prompt string
A natural-language instruction that guides the description style or focus, for example
focus on describing colors. If omitted, a default prompt is used.
Show schema
- job_id stringRequired
Unique identifier of the analysis job, used to poll for the result.
example"550e8400e29b41d4a716446655440000" - status stringRequired
Current status of the analysis job.
example"pending"enum"pending""completed""failed" - visual_transcription AIVideoAnalysisVisualTranscriptionnullable
Details of the generated visual transcript file, stored as a raw asset in your product environment (present when the status is
completed).ShowHide child attributes of visual_transcription
- asset_id string
Cloudinary asset ID of the visual transcript file.
- public_id string
Cloudinary public ID of the visual transcript file.
- resource_type string
Cloudinary resource type of the visual transcript file.
- delivery_type string
Cloudinary delivery type of the visual transcript file.
- url string
HTTPS URL of the visual transcript file.
- message string
Error message when the analysis has failed.
Show schema
Details of the generated visual transcript file, stored as a raw asset in your product environment (present when the status is completed).
- asset_id string
Cloudinary asset ID of the visual transcript file.
- public_id string
Cloudinary public ID of the visual transcript file.
- resource_type string
Cloudinary resource type of the visual transcript file.
- delivery_type string
Cloudinary delivery type of the visual transcript file.
- url string
HTTPS URL of the visual transcript file.
Show schema
- request_id stringRequired
Unique identifier of the API request, useful for support and debugging.
example"6ec0bd7f11c043da975e2a8ad9ebae0b" - data AIVideoAnalysisResponseRequired
ShowHide child attributes of data
- job_id stringRequired
Unique identifier of the analysis job, used to poll for the result.
example"550e8400e29b41d4a716446655440000" - status stringRequired
Current status of the analysis job.
example"pending"enum"pending""completed""failed" - visual_transcription AIVideoAnalysisVisualTranscriptionnullable
Details of the generated visual transcript file, stored as a raw asset in your product environment (present when the status is
completed).ShowHide child attributes of visual_transcription
- asset_id string
Cloudinary asset ID of the visual transcript file.
- public_id string
Cloudinary public ID of the visual transcript file.
- resource_type string
Cloudinary resource type of the visual transcript file.
- delivery_type string
Cloudinary delivery type of the visual transcript file.
- url string
HTTPS URL of the visual transcript file.
- message string
Error message when the analysis has failed.
Show schema
- request_id stringRequired
Unique identifier of the API request, useful for support and debugging.
example"6ec0bd7f11c043da975e2a8ad9ebae0b" - error objectRequired
Details of the error that occurred.
ShowHide child attributes of error
- message string
Human-readable description of the error.