Create a YouTube Subtitle Collection Job

POST/v1/youtube/videos/{video_id}/subtitles

Creates an asynchronous yt-dlp-backed subtitle extraction job for one YouTube video. Each successfully delivered language track costs 5 Credits; a job without a delivered track is released without charge.

On this page

Request example

Replace placeholders with your values. Use your Team API key for authenticated requests.

API base https://kieapi.com

curl -X POST "https://kieapi.com/v1/youtube/videos/{video_id}/subtitles" \
  -H "Authorization: Bearer $SPIDER_API_KEY" \
  -H 'Idempotency-Key: docs-example-01' \
  -H "Content-Type: application/json" \
  -d '{}'

Authentication

BearerAuth

Parameters

video_id path · string required
Idempotency-Key header · string: Caller-generated key, up to 128 characters, that identifies one API Market write and its billing event. Reuse the same key only when retrying the same logical request. Replays do not create another reservation or capture.

Request body required

application/json

YoutubeSubtitleJobCreateRequest

languages array of string

Default: ["en"]

include_auto boolean

Default: true

format string

Allowed: "vtt", "srt", "json3", "best"

Default: "vtt"

Responses

202 YouTube subtitle job accepted.

application/json

YoutubeMediaJobResponse

job YoutubeMediaJob required

400 Request validation failed.

application/json

PublicErrorResponse

error PublicError required

401 Missing or invalid API key.

application/json

PublicErrorResponse

error PublicError required

402 The Team does not have enough available Credits for the maximum reservation.

application/json

PublicErrorResponse

error PublicError required

403 Authenticated principal cannot access this resource.

application/json

PublicErrorResponse

error PublicError required

409 Billing settlement requires reconciliation, or the idempotency key was reused for a different logical request.

application/json

PublicErrorResponse

error PublicError required

429 Temporary rate limit.

application/json

PublicErrorResponse

error PublicError required

503 Required runtime service is unavailable.

application/json

PublicErrorResponse

error PublicError required

Schemas

Field definitions and complete validation rules for this API. Follow a type link to its definition.

YoutubeSubtitleJobCreateRequest

object

languages array of string

Default: ["en"]

include_auto boolean

Default: true

format string

Allowed: "vtt", "srt", "json3", "best"

Default: "vtt"

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "languages": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": [
        "en"
      ]
    },
    "include_auto": {
      "type": "boolean",
      "default": true
    },
    "format": {
      "type": "string",
      "enum": [
        "vtt",
        "srt",
        "json3",
        "best"
      ],
      "default": "vtt"
    }
  }
}

YoutubeMediaJobResponse

object

job YoutubeMediaJob required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "job"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/YoutubeMediaJob"
    }
  }
}

YoutubeMediaJob

object

id string required
platform string required: Allowed: "youtube"
kind string required: Allowed: "download", "subtitles", "comments"
status string required: Allowed: "queued", "running", "completed", "failed", "canceled"
video_id string required
video_url string required
progress YoutubeMediaProgress required
error YoutubeMediaError or null
created_at string | null (date-time)
updated_at string | null (date-time)
started_at string | null (date-time)
finished_at string | null (date-time)

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "platform",
    "kind",
    "status",
    "video_id",
    "video_url",
    "progress"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "platform": {
      "type": "string",
      "enum": [
        "youtube"
      ]
    },
    "kind": {
      "type": "string",
      "enum": [
        "download",
        "subtitles",
        "comments"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "running",
        "completed",
        "failed",
        "canceled"
      ]
    },
    "video_id": {
      "type": "string"
    },
    "video_url": {
      "type": "string"
    },
    "progress": {
      "$ref": "#/components/schemas/YoutubeMediaProgress"
    },
    "error": {
      "anyOf": [
        {
          "$ref": "#/components/schemas/YoutubeMediaError"
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "updated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "started_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "finished_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}

YoutubeMediaProgress

object

stage string required
percent number | null
downloaded_bytes integer | null
total_bytes integer | null
speed_bytes_per_second number | null

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "stage"
  ],
  "properties": {
    "stage": {
      "type": "string"
    },
    "percent": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0,
      "maximum": 100
    },
    "downloaded_bytes": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "total_bytes": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "speed_bytes_per_second": {
      "type": [
        "number",
        "null"
      ],
      "minimum": 0
    }
  }
}

YoutubeMediaError

object

code string required
message string required
retryable boolean: Default: false

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "message"
  ],
  "properties": {
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "retryable": {
      "type": "boolean",
      "default": false
    }
  }
}

PublicErrorResponse

object

error PublicError required

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "$ref": "#/components/schemas/PublicError"
    }
  }
}

PublicError

object

code string required: Allowed: "seoapi_price_pending", "seoapi_unavailable", "seoapi_busy", "seoapi_not_found", "seoapi_rate_limited", "seoapi_budget_exceeded", "seoapi_idempotency_conflict", "seoapi_insufficient_credits", "seoapi_admission_failed", "seoapi_execution_interrupted", "seoapi_delivery_unknown", "seoapi_response_invalid", "seoapi_model_unsupported", "seoapi_model_options_invalid", "seoapi_provider_rejected", "seo_price_pending", "seo_provider_blocked", "seo_local_rate_limited", "seo_fallback_unavailable", "seo_fallback_budget_exceeded", "seo_pagination_expired", "seo_delivery_uncertain", "seo_auth_required", "seo_initialization_required", "seo_permission_denied", "seo_verification_required", "seo_rate_limited", "seo_upstream_unavailable", "seo_transport_failed", "seo_invalid_response", "seo_rpc_error", "seo_period_unavailable", "seo_account_unavailable", "seo_session_busy", "seo_configuration_required", "validation_error", "invalid_request", "unsupported_feature", "authentication_required", "permission_denied", "not_found", "run_not_found", "crawl_not_found", "artifact_not_found", "session_not_found", "profile_not_found", "profile_in_use", "profile_not_ready", "profile_not_cloneable", "profile_limit_reached", "profile_proxy_conflict", "proxy_not_found", "proxy_unavailable", "invalid_session_options", "invalid_query_options", "invalid_cursor", "idempotency_key_required", "browser_session_limit_reached", "browser_capacity_exhausted", "browser_start_timeout", "browser_runtime_unavailable", "session_not_active", "controller_already_connected", "browser_relay_unavailable", "precondition_required", "precondition_failed", "timeout", "run_not_ready", "artifact_expired", "quota_exceeded", "insufficient_credits", "billing_reconciliation_required", "rate_limited", "fetch_failed", "render_failed", "maps_rate_limited", "maps_challenge", "maps_schema_changed", "maps_invalid_response", "maps_transport_failed", "maps_page_budget_exhausted", "google_trends_rate_limited", "google_trends_challenge", "google_trends_explore_failed", "google_trends_widget_missing", "google_trends_related_failed", "google_trends_invalid_response", "google_trends_transport_failed", "google_trends_collection_failed", "google_ads_account_context_missing", "google_ads_batch_failed", "google_ads_browser_context_missing", "google_ads_browser_unavailable", "google_ads_collection_failed", "google_ads_page_failed", "google_ads_protocol_drift", "google_ads_rate_limited", "google_ads_timeout", "twitter_provider_unavailable", "twitter_provider_rejected", "twitter_submission_unknown", "wechat_transport_failed", "wechat_rate_limited", "wechat_invalid_response", "wechat_redirect_rejected", "wechat_verification_required", "wechat_parse_failed", "blackhatworld_search_failed", "blackhatworld_no_results", "reddit_read_failed", "idempotency_conflict", "idempotency_in_progress", "service_unavailable", "internal_error"
message string required
type string required: Allowed: "auth", "validation", "quota", "rate_limit", "not_found", "execution", "conflict", "internal"
retryable boolean required
request_id string | null
details object

Complete schema

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "code",
    "message",
    "type",
    "retryable"
  ],
  "properties": {
    "code": {
      "type": "string",
      "enum": [
        "seoapi_price_pending",
        "seoapi_unavailable",
        "seoapi_busy",
        "seoapi_not_found",
        "seoapi_rate_limited",
        "seoapi_budget_exceeded",
        "seoapi_idempotency_conflict",
        "seoapi_insufficient_credits",
        "seoapi_admission_failed",
        "seoapi_execution_interrupted",
        "seoapi_delivery_unknown",
        "seoapi_response_invalid",
        "seoapi_model_unsupported",
        "seoapi_model_options_invalid",
        "seoapi_provider_rejected",
        "seo_price_pending",
        "seo_provider_blocked",
        "seo_local_rate_limited",
        "seo_fallback_unavailable",
        "seo_fallback_budget_exceeded",
        "seo_pagination_expired",
        "seo_delivery_uncertain",
        "seo_auth_required",
        "seo_initialization_required",
        "seo_permission_denied",
        "seo_verification_required",
        "seo_rate_limited",
        "seo_upstream_unavailable",
        "seo_transport_failed",
        "seo_invalid_response",
        "seo_rpc_error",
        "seo_period_unavailable",
        "seo_account_unavailable",
        "seo_session_busy",
        "seo_configuration_required",
        "validation_error",
        "invalid_request",
        "unsupported_feature",
        "authentication_required",
        "permission_denied",
        "not_found",
        "run_not_found",
        "crawl_not_found",
        "artifact_not_found",
        "session_not_found",
        "profile_not_found",
        "profile_in_use",
        "profile_not_ready",
        "profile_not_cloneable",
        "profile_limit_reached",
        "profile_proxy_conflict",
        "proxy_not_found",
        "proxy_unavailable",
        "invalid_session_options",
        "invalid_query_options",
        "invalid_cursor",
        "idempotency_key_required",
        "browser_session_limit_reached",
        "browser_capacity_exhausted",
        "browser_start_timeout",
        "browser_runtime_unavailable",
        "session_not_active",
        "controller_already_connected",
        "browser_relay_unavailable",
        "precondition_required",
        "precondition_failed",
        "timeout",
        "run_not_ready",
        "artifact_expired",
        "quota_exceeded",
        "insufficient_credits",
        "billing_reconciliation_required",
        "rate_limited",
        "fetch_failed",
        "render_failed",
        "maps_rate_limited",
        "maps_challenge",
        "maps_schema_changed",
        "maps_invalid_response",
        "maps_transport_failed",
        "maps_page_budget_exhausted",
        "google_trends_rate_limited",
        "google_trends_challenge",
        "google_trends_explore_failed",
        "google_trends_widget_missing",
        "google_trends_related_failed",
        "google_trends_invalid_response",
        "google_trends_transport_failed",
        "google_trends_collection_failed",
        "google_ads_account_context_missing",
        "google_ads_batch_failed",
        "google_ads_browser_context_missing",
        "google_ads_browser_unavailable",
        "google_ads_collection_failed",
        "google_ads_page_failed",
        "google_ads_protocol_drift",
        "google_ads_rate_limited",
        "google_ads_timeout",
        "twitter_provider_unavailable",
        "twitter_provider_rejected",
        "twitter_submission_unknown",
        "wechat_transport_failed",
        "wechat_rate_limited",
        "wechat_invalid_response",
        "wechat_redirect_rejected",
        "wechat_verification_required",
        "wechat_parse_failed",
        "blackhatworld_search_failed",
        "blackhatworld_no_results",
        "reddit_read_failed",
        "idempotency_conflict",
        "idempotency_in_progress",
        "service_unavailable",
        "internal_error"
      ]
    },
    "message": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": [
        "auth",
        "validation",
        "quota",
        "rate_limit",
        "not_found",
        "execution",
        "conflict",
        "internal"
      ]
    },
    "retryable": {
      "type": "boolean"
    },
    "request_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "details": {
      "type": "object",
      "additionalProperties": true
    }
  }
}