> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Get AI Clipping > Returns the full job resource including produced clips, statuses, and presigned download URLs. ## OpenAPI ````yaml /openapi/external-api.json get /v3/ai-clipping/{job_id} openapi: 3.1.0 info: title: HeyGen External API version: 1.0.0 description: >- HeyGen's external API for programmatic AI video creation. See https://docs.heygen.com for full documentation. contact: name: HeyGen Product Infra url: https://heygen.com servers: - url: https://api.heygen.com description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Video Agent description: Create videos from text prompts using AI - name: Videos description: Create, list, retrieve, and delete videos - name: Templates description: Generate videos from reusable templates by replacing their variables - name: Voices description: Text-to-speech and voice management - name: Audio description: Search the background-music and sound-effects catalog - name: Video Translate description: Translate videos into other languages - name: AI Clipping description: Turn long-form videos into ready-to-share short clips with captions - name: Batches description: Create and track batches of videos. - name: Video Translation Batches description: Create and track batches of video translations. - name: Lipsync Batches description: Create and track batches of lipsyncs. - name: Asset Batches description: Create and track batches of direct-to-S3 asset uploads. - name: User description: Account information and billing - name: Avatars description: List and manage avatars and looks - name: Assets description: Upload files for use in video creation - name: Webhooks description: Manage webhook endpoints and events - name: Lipsync description: Dub or replace audio on existing videos - name: Brand description: >- Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations) - name: HyperFrames description: Render HyperFrames composition zips into video — separate from /v3/videos - name: Filler Word Removal description: '' paths: /v3/ai-clipping/{job_id}: get: tags: - AI Clipping summary: Get AI Clipping description: >- Returns the full job resource including produced clips, statuses, and presigned download URLs. operationId: getAiClippingV3 parameters: - name: job_id in: path required: true schema: type: string description: Unique AI clip job identifier responses: '200': description: Successful response content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/AiClippingDetail' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' '401': description: Authentication failed content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: unauthorized message: Invalid or expired API key. Verify your x-api-key header. param: null doc_url: null '404': description: Resource not found content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: not_found message: AI clip not found. param: null doc_url: null '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: rate_limit_exceeded message: >- Too many requests. Retry after the duration specified in the Retry-After header. param: null doc_url: null headers: Retry-After: description: Seconds to wait before retrying schema: type: integer security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: AiClippingDetail: description: Full job resource returned by Get, List, and webhook payloads. properties: id: description: Unique job identifier. title: Id type: string title: anyOf: - type: string - type: 'null' default: null description: Display title. title: Title status: $ref: '#/components/schemas/JobStatus' description: Job lifecycle status. input_language: anyOf: - type: string - type: 'null' default: null description: Detected or supplied source language code. title: Input Language source_duration: anyOf: - type: number - type: 'null' default: null description: Duration of the source video in seconds. title: Source Duration output_settings: anyOf: - $ref: '#/components/schemas/HighlightOutputSettings' - type: 'null' default: null description: Currently omitted from Get, List, and webhook responses. clips: description: Produced clips. Empty until the job's first clip is rendered. items: $ref: '#/components/schemas/Clip' title: Clips type: array progress: default: 0 description: >- Approximate progress (0-100). 100 when all clips completed. GET /v3/ai-clipping/{id} returns live in-flight progress; the list endpoint reports a coarse value (0 until completed, then 100). Poll the single-get endpoint for granular progress. maximum: 100 minimum: 0 title: Progress type: integer callback_id: anyOf: - type: string - type: 'null' default: null description: Client-provided callback ID. title: Callback Id created_at: anyOf: - type: integer - type: 'null' default: null description: Unix timestamp (seconds) of job creation. title: Created At failure_message: anyOf: - type: string - type: 'null' default: null description: Error description. Only present when status=failed. title: Failure Message required: - id - status title: AiClippingDetail type: object StandardAPIError: type: object properties: code: type: string description: Machine-readable error code example: invalid_parameter message: type: string description: Human-readable error message example: Video not found param: type: - string - 'null' description: Which request field caused the error doc_url: type: - string - 'null' description: Link to error documentation errors: type: array description: >- Per-item error details for batch/multi-node failures (e.g. graph compilation errors by node). items: $ref: '#/components/schemas/StandardAPIErrorDetail' required: - code - message JobStatus: description: Public job lifecycle. enum: - pending - running - completed - failed - cancelled title: JobStatus type: string HighlightOutputSettings: additionalProperties: false description: Configuration for the clips the job will produce. properties: duration_types: description: >- One or more target clip durations to produce. Each produces a separate clip. items: $ref: '#/components/schemas/OutputDuration' maxItems: 4 minItems: 1 title: Duration Types type: array aspect_ratio: $ref: '#/components/schemas/OutputAspectRatio' default: portrait description: >- Aspect ratio for all produced clips. Default 'portrait' (9:16, social-ready). captions: default: true description: Burn captions into the clips. Set false to disable. title: Captions type: boolean caption_style: $ref: '#/components/schemas/CaptionStylePreset' default: outline_classic description: >- Named caption style preset (e.g. 'outline_classic', 'bold'). Defaults to 'outline_classic'. Null or unrecognized values fall back to the default. prompt: anyOf: - maxLength: 500 type: string - type: 'null' default: null description: >- Optional editorial guidance for the highlight model. Max 500 characters. title: Prompt title: HighlightOutputSettings type: object Clip: description: A single produced clip. Returned inline inside AiClippingDetail. properties: id: description: Unique clip identifier. title: Id type: string status: $ref: '#/components/schemas/ClipStatus' description: Per-clip status. duration_seconds: anyOf: - type: number - type: 'null' default: null description: Final clip duration in seconds. Null until status=completed. title: Duration Seconds aspect_ratio: anyOf: - $ref: '#/components/schemas/OutputAspectRatio' - type: 'null' default: null description: Clip aspect ratio. Null until status=completed. title: anyOf: - type: string - type: 'null' default: null description: Model-generated clip title. title: Title virality_score: anyOf: - maximum: 100 minimum: 0 type: integer - type: 'null' default: null description: Model-predicted virality score (0-100). Null until status=completed. title: Virality Score thumbnail_url: anyOf: - type: string - type: 'null' default: null description: Presigned thumbnail URL. Null until status=completed. title: Thumbnail Url video_url: anyOf: - type: string - type: 'null' default: null description: Presigned MP4 download URL. Null until status=completed. title: Video Url failure_message: anyOf: - type: string - type: 'null' default: null description: Per-clip failure description. Currently always null. title: Failure Message required: - id - status title: Clip type: object StandardAPIErrorDetail: type: object properties: code: type: string description: Machine-readable error code example: unknown_node_type message: type: string description: Human-readable error message example: Unknown node type node_id: type: string description: Graph node id this error pertains to, if applicable port: type: string description: Port name on the node this error pertains to, if applicable path: type: string description: Field path within the item this error pertains to, if applicable required: - code - message OutputDuration: description: Target clip duration. ``long`` returns the model's choice >180s. enum: - '30' - '60' - '180' - long title: OutputDuration type: string OutputAspectRatio: description: Output aspect ratio for produced clips. enum: - landscape - portrait - square title: OutputAspectRatio type: string CaptionStylePreset: description: Available caption style presets. enum: - subtle_gray - shadow_mint - subtle_cyan - stamp_red - retro_gold - block_dark - racing - modern_dark - modern_boxed - chunky - clean - shadow_lime - tag_yellow - pop_purple - spotlight - outline_classic - exotic - golden - simple - pop_single - energy - bold - elegant - neon_pink title: CaptionStylePreset type: string ClipStatus: description: >- Per-clip lifecycle. A job can produce N clips, each completing separately. enum: - pending - completed - failed title: ClipStatus type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: HeyGen API key. Obtain from your HeyGen dashboard. BearerAuth: type: http scheme: bearer description: OAuth2 bearer token. ````