SpideyDataAPI Reference
OpenAPI YAMLProduct Console
API navigation YouTube
FetchExtractBrowserCrawlRunsYouTubeRedditGoogle MapsWeChatBlackHatWorldGoogle TrendsGoogle AdsTwitterSimilarwebSemrushSEO APISERP
Monitors7
Videos5
Media jobs3
YouTubeVideos

Create a YouTube Video Download Job

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

Creates an asynchronous yt-dlp-backed media download job for one YouTube video. A successful job costs 100 Credits plus 1,000 Credits per started 100,000,000 downloaded bytes and 100 Credits per started 600 worker seconds. The request limits bound the reservation; missing or incomplete measurement does not capture a 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}/downloads" \
  -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

YoutubeDownloadJobCreateRequest

format string

Allowed: "bestvideo*+bestaudio/best", "bestvideo[height<=1080]+bestaudio/best[height<=1080]/best", "bestvideo[height<=720]+bestaudio/best[height<=720]/best", "best[height<=480]/best", "bestaudio/best"

Default: "bestvideo*+bestaudio/best"

audio_only boolean

Default: false

include_info_json boolean

Default: true

include_thumbnail boolean

Default: true

include_subtitles boolean

Default: false

subtitle_languages array of string

Default: []

include_auto_subtitles boolean

Default: false

max_spend_credits integer
Maximum Credits that may be reserved and captured for this download.

Default: 10300

max_download_bytes integer (int64)
Hard cumulative byte limit across streams, fragments, and retries.

Default: 1000000000

max_worker_seconds integer
Hard limit for cumulative worker occupancy across attempts.

Default: 1200

Responses

202 YouTube download 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.

YoutubeDownloadJobCreateRequest

object

format string

Allowed: "bestvideo*+bestaudio/best", "bestvideo[height<=1080]+bestaudio/best[height<=1080]/best", "bestvideo[height<=720]+bestaudio/best[height<=720]/best", "best[height<=480]/best", "bestaudio/best"

Default: "bestvideo*+bestaudio/best"

audio_only boolean

Default: false

include_info_json boolean

Default: true

include_thumbnail boolean

Default: true

include_subtitles boolean

Default: false

subtitle_languages array of string

Default: []

include_auto_subtitles boolean

Default: false

max_spend_credits integer
Maximum Credits that may be reserved and captured for this download.

Default: 10300

max_download_bytes integer (int64)
Hard cumulative byte limit across streams, fragments, and retries.

Default: 1000000000

max_worker_seconds integer
Hard limit for cumulative worker occupancy across attempts.

Default: 1200

Complete schema
{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "format": {
      "type": "string",
      "enum": [
        "bestvideo*+bestaudio/best",
        "bestvideo[height<=1080]+bestaudio/best[height<=1080]/best",
        "bestvideo[height<=720]+bestaudio/best[height<=720]/best",
        "best[height<=480]/best",
        "bestaudio/best"
      ],
      "default": "bestvideo*+bestaudio/best"
    },
    "audio_only": {
      "type": "boolean",
      "default": false
    },
    "include_info_json": {
      "type": "boolean",
      "default": true
    },
    "include_thumbnail": {
      "type": "boolean",
      "default": true
    },
    "include_subtitles": {
      "type": "boolean",
      "default": false
    },
    "subtitle_languages": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "default": []
    },
    "include_auto_subtitles": {
      "type": "boolean",
      "default": false
    },
    "max_spend_credits": {
      "type": "integer",
      "minimum": 1200,
      "maximum": 100000,
      "default": 10300,
      "description": "Maximum Credits that may be reserved and captured for this download."
    },
    "max_download_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 1,
      "maximum": 5000000000,
      "default": 1000000000,
      "description": "Hard cumulative byte limit across streams, fragments, and retries."
    },
    "max_worker_seconds": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3600,
      "default": 1200,
      "description": "Hard limit for cumulative worker occupancy across attempts."
    }
  }
}

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
    }
  }
}