Downloads

SocialKit offers two download styles through this SDK. The platform-specific synchronous methods return a download URL in one request and suit shorter content. The v2 service starts a job and lets you poll or wait for it; it is designed for long or large videos. 1 2

Choose the appropriate workflow

Workflow	SDK call	Supported platforms	Best use
Synchronous download	YouTube.Download, TikTok.Download, Instagram.Download	YouTube, TikTok, Instagram	Short content that should return in a single request.
Asynchronous v2 job	Downloads.Start, Downloads.Get, Downloads.Wait	YouTube, TikTok, Instagram, Facebook	Long-form or large content that could outlast one request.

The upstream v2 API supports up to 1080p and a maximum file size of 2 GB per job. A completed job returns a temporary download URL; SocialKit documents the usual URL lifetime as one hour, so fetch it promptly. 1

Synchronous downloads

Create a DownloadRequest with the content URL and optional output preferences. All optional fields are pointers; leave them nil if you want upstream defaults.

result, meta, err := client.YouTube.Download(ctx, &socialkit.DownloadRequest{
    URL:     "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    Format:  socialkit.StringPtr("mp4"),
    Quality: socialkit.StringPtr("720p"),
})
if err != nil {
    return err
}

fmt.Println("URL:", result.DownloadURL)
fmt.Println("title:", result.Title)
fmt.Println("format:", result.Format)
fmt.Println("quality:", result.Quality)
if meta.CreditsUsed != nil {
    fmt.Printf("credits used: %.0f\n", *meta.CreditsUsed)
}

DownloadResult includes the source URL, title, duration, download URL, format, quality, expiry information, file-size fields, and credit use when present. The precise format and quality choices are endpoint-level API capabilities; confirm them in the live SocialKit reference before presenting a fixed list in your application UI. 2 3

Optional DownloadRequest field	Purpose
Format	Request the output container or audio format.
Quality	Request a maximum quality.
Country	Route the operation through a country for region-related access where supported.

Start an asynchronous v2 job

Downloads.Start validates that platform is one of youtube, tiktok, instagram, or facebook, then posts a V2DownloadRequest to the corresponding v2 route. 3

job, meta, err := client.Downloads.Start(ctx, "youtube", &socialkit.V2DownloadRequest{
    URL:         "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    Format:      "mp4",
    Quality:     "720p",
    MaxDuration: socialkit.IntPtr(1800), // Reject sources over 30 minutes.
})
if err != nil {
    return err
}

fmt.Printf("job %s is %s\n", job.JobID, job.Status)
_ = meta

MaxDuration is expressed in seconds. SocialKit states that a v2 job exceeding this cap fails before downloading and incurs no credit charge, which makes it a useful guardrail for cost-sensitive workloads. 1

Poll manually

Downloads.Get reads the current state. The upstream job lifecycle consists of queued, processing, ready, and failed. ready includes the download URL and metadata; failed includes a human-readable error and, when supplied, a stable error code and retryability signal. 1 2

for {
    job, _, err := client.Downloads.Get(ctx, jobID)
    if err != nil {
        return err
    }

    switch job.Status {
    case "ready":
        fmt.Println(job.DownloadURL)
        return nil
    case "failed":
        return fmt.Errorf("download job failed: %s (%s)", job.Error, job.ErrorCode)
    }

    select {
    case <-ctx.Done():
        return ctx.Err()
    case <-time.After(3 * time.Second):
    }
}

Polling itself is documented as non-billable. Nevertheless, use a bounded interval and a context deadline to avoid a runaway process. 1

Let the SDK wait for completion

Downloads.Wait implements the polling loop for you. With opts == nil, it polls every two seconds until the supplied context ends. When you set MaxAttempts, the method stops after that many polls; with BackoffFactor greater than 1, it multiplies the interval after each attempt. 3

finalJob, meta, err := client.Downloads.Wait(ctx, job.JobID, &socialkit.WaitOptions{
    Interval:      3 * time.Second,
    MaxAttempts:   20,
    BackoffFactor: 1.5,
})
if err != nil {
    if errors.Is(err, socialkit.ErrAsyncJobFailed) {
        var failed *socialkit.AsyncJobFailedError
        if errors.As(err, &failed) {
            log.Printf("job failed: %s; retryable=%t", failed.Message, failed.Retryable)
        }
    }
    return err
}

fmt.Printf("download ready: %s\n", finalJob.DownloadURL)
if finalJob.CreditsCost != nil {
    fmt.Printf("credits cost: %.0f\n", *finalJob.CreditsCost)
}
_ = meta

When the remote job reaches failed, Wait returns AsyncJobFailedError, which matches ErrAsyncJobFailed with errors.Is. A non-ready terminal outcome is therefore distinct from an HTTP API error or a context deadline. 3 4

V2 job fields

V2Job field	Meaning
JobID	Identifier to pass to Get or Wait.
Status	queued, processing, ready, or failed.
Platform, URL, Format, Quality	Accepted source and output choices.
DownloadURL, ExpiresIn	Temporary result URL and its lifetime when ready.
DurationSeconds, FileSize, FileSizeMB, Title, Thumbnail	Completion metadata when available.
CreditsCost, Billed	Cost and billing metadata when available.
Error, ErrorCode, Retryable	Failure details when status is failed.

Credit considerations

SocialKit documents v2 billing as occurring once when a job completes. Its current guide states that audio and video up to 480p cost one credit per started minute, while 720p and 1080p video cost four credits per started minute. These values are upstream policy and can change; use the returned CreditsCost, Billed, and response metadata for records rather than duplicating estimates in application logic. 1

Production checklist

Before placing a v2 workflow into production, give each job an application context deadline, persist the job ID if work must survive process restarts, inspect Retryable for a failed job, and copy a ready result before its temporary URL expires. Avoid logging the full download URL if it is sensitive in your environment. Enable HTTP retries only after considering the cost and idempotency implications described in Client Configuration.

References