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.

v0.1.0OAS 3.0.3

AI Video Analysis API (Beta)

Download OpenAPI Document

Use 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.

AI Video Analysis

Generate a visual transcription of a video and poll the analysis job.

Create an AI Video Analysis job

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.

AIVideoAnalysisPayload
  • 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
application/json
AIVideoAnalysisWrappedResponse
  • 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
application/json
ErrorWrappedResponse
  • 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
application/json
ErrorWrappedResponse
  • 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
application/json
ErrorWrappedResponse
  • 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.

POST/ai_video_analysis
curl -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"
}'
Response
{
  "request_id": "6ec0bd7f11c043da975e2a8ad9ebae0b",
  "data": {
    "job_id": "550e8400e29b41d4a716446655440000",
    "status": "pending"
  }
}

Poll an AI Video Analysis job

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)
application/json
AIVideoAnalysisWrappedResponse
  • 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
application/json
ErrorWrappedResponse
  • 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
application/json
ErrorWrappedResponse
  • 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
application/json
ErrorWrappedResponse
  • 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.

GET/ai_video_analysis/{jobId}
curl 'https://api.cloudinary.com/v2/video/CLOUD_NAME/ai_video_analysis/{jobId}' \
  -u 'API_KEY:API_SECRET'
Response
{
  "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"
    }
  }
}

Models

AIVideoAnalysisPayload

Show schema
object
  • 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.

AIVideoAnalysisResponse

Show schema
object
  • 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.

AIVideoAnalysisVisualTranscription

Show schema
object

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.

AIVideoAnalysisWrappedResponse

Show schema
object
  • 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.

ErrorWrappedResponse

Show schema
object
  • 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.