ADownload Developer API

Integrate downloads from 1,000+ public media sites and platforms into an agent, backend service, script, or application.

Última actualización: 2026-08-12

Overview

ADownload provides an asynchronous REST API for authorized public media across 1,000+ sites and platforms. The same API works for AI agents, backend services, command-line scripts, automation platforms, and your own product.

Base path: /api/v1
MCP endpoint: /mcp
MCP protocol: 2026-07-28 over Streamable HTTP
OpenAPI 3.1: /api/v1/openapi.json
Capability discovery: /api/v1/capabilities
Authentication: Bearer API key
Response format: JSON
Output: MP4 video, M4A audio, or 192 kbps MP3 audio
Coverage: 1,000+ public media sites and platforms

Third-party agents should use /mcp. Backend services, scripts, and generated SDKs should use /api/v1.

Third-party agents: MCP

The MCP endpoint is https://your-domain.example/mcp and uses the same sk_... API key as the Developer API. The server accepts the current 2026-07-28 protocol only; it does not run a legacy compatibility path. Native and server-side MCP clients normally omit Origin. Add browser MCP client origins to the server-side MCP_ALLOWED_ORIGINS setting.

The following is the generic configuration shape. Supply the API key through your MCP client's secret store or environment-variable interpolation; do not commit it to a repository:

{
  "mcpServers": {
    "adownload": {
      "url": "https://your-domain.example/mcp",
      "headers": {
        "Authorization": "Bearer ${DOWNLOADER_API_KEY}"
      }
    }
  }
}

The MCP server exposes these tools:

get_capabilities — read formats, costs, limits, and source policy
get_credit_balance — check the permanent USD balance
submit_download — create an idempotent asynchronous job
get_download_job — refresh one job
wait_for_download — poll for up to 55 seconds
list_download_jobs — list recent jobs
get_download_artifact — return a temporary signed MCP Resource Link
cancel_download — cancel an active job and refund it automatically

get_download_artifact never reads a large media file into MCP server memory. The Agent host should stream the returned Resource Link to local storage. Call the tool again to refresh an expired URL.

Architecture and job lifecycle

Creating a download does not hold the HTTP connection open while media is processed. The SaaS API authenticates the caller, reserves USD balance, and creates a job. A separate processing Worker runs the durable download workflow and stores the result in private temporary storage.

submitting → accepted → queued → running → ready

Terminal error states are failed, canceled, and expired. Reserved balance is automatically restored for all three. A ready artifact is normally retained for one hour.

1. Create an API key

Sign in, open Settings → API Keys, and create a key. The full sk_... value is displayed only once. Store it in a secret manager or server-side environment variable.

Never embed an API key in public browser JavaScript, a mobile binary, a public repository, logs, or analytics events. Calls from a browser are CORS-enabled, but exposing a permanent key to end users is not safe; proxy such calls through your backend.

export DOWNLOADER_BASE_URL="https://your-downloader-domain.com"
export DOWNLOADER_API_KEY="sk_..."

2. Discover current capabilities

This endpoint is public and can be used during setup or runtime validation.

curl "$DOWNLOADER_BASE_URL/api/v1/capabilities"

It reports current platform coverage, profiles, USD balance costs, output formats, source restrictions, artifact lifetime, signed URL lifetime, and request limits.

1,000+ platform coverage

ADownload covers 1,000+ public media sites and platforms, including video, social media, podcasts, news, education, and pages containing embedded media. One integration handles these source categories without maintaining separate platform-specific downloaders.

Platform compatibility changes as source sites change. The reliable compatibility check is to submit the public URL and inspect the returned job result.

Profile	Cost	Maximum video height	Maximum artifact	Processing timeout
`economy`	$0.01 USD balance	720p	750 MiB	15 minutes
`large`	$0.05 USD balance	1080p	2 GiB	30 minutes

Video is delivered as MP4 without video transcoding. Audio is available as M4A or MP3 at 192 kbps. Actual source compatibility depends on the current extractor and whether the public source exposes a usable format.

Product feature boundary

Capability	Supported now
Public single-video URLs across 1,000+ platforms	Yes
Embedded media and generic public web pages	Yes, when the extractor finds usable media
MP4 video up to 720p or 1080p	Yes, subject to profile and source formats
M4A or 192 kbps MP3 audio	Yes
Async jobs, polling, cancellation, idempotency, and bounded retries	Yes
Private one-hour artifacts, signed URLs, HEAD, Range, and SHA-256	Yes
Playlists, live streams, login/cookie sources, private media, or DRM	No
Subtitles, thumbnails, arbitrary low-level downloader options, or guaranteed access bypass	No

3. Check the USD balance

The API retains the credits and creditPolicy field names for backward compatibility. Their numeric values are USD amounts: paying $1 adds $1.00 to the balance.

curl "$DOWNLOADER_BASE_URL/api/v1/credits" \
  -H "Authorization: Bearer $DOWNLOADER_API_KEY"

{
  "ok": true,
  "data": {
    "credits": 5,
    "creditPolicy": {
      "expires": false,
      "economyCost": 0.01,
      "largeCost": 0.05
    }
  }
}

4. Create a download

Generate one Idempotency-Key for each logical job and keep it stable across network retries.

curl -X POST "$DOWNLOADER_BASE_URL/api/v1/downloads" \
  -H "Authorization: Bearer $DOWNLOADER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8f52cbd3-video" \
  --data '{
    "sourceUrl": "https://media.example/video",
    "kind": "video",
    "profile": "economy",
    "videoMaxHeight": 720
  }'

Audio example:

{
  "sourceUrl": "https://media.example/video",
  "kind": "audio",
  "profile": "economy",
  "audioFormat": "mp3"
}

Request fields:

Field	Required	Values and behavior
`sourceUrl`	Yes	Public HTTP or HTTPS URL, up to 4,096 characters
`kind`	No	`video` by default, or `audio`
`profile`	No	`economy` by default, or `large`
`videoMaxHeight`	Video only	144–720 for economy; 144–1080 for large
`audioFormat`	Audio only	`m4a` by default, or `mp3`

Idempotency guarantees

Keys may contain safe ASCII characters and must be 8–128 characters long.
Retrying the same key with the same normalized request returns the existing job and does not charge the balance again.
Reusing a key with a different request returns 409 idempotency_conflict.
Use a new key when you intentionally create another download or retry a terminal failed job.
Requests without a key are accepted, but safe retry behavior is not guaranteed.

5. Poll until completion

curl "$DOWNLOADER_BASE_URL/api/v1/downloads/JOB_ID" \
  -H "Authorization: Bearer $DOWNLOADER_API_KEY"

Use exponential backoff rather than polling continuously. A practical schedule is 2, 4, 8, then 10 seconds between requests.

async function waitForDownload(baseUrl, apiKey, jobId) {
  const terminal = new Set(['ready', 'failed', 'canceled', 'expired']);
  let delay = 2000;

  while (true) {
    const response = await fetch(`${baseUrl}/api/v1/downloads/${jobId}`, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    const body = await response.json();
    if (!response.ok)
      throw new Error(body.error?.message || 'API request failed');
    if (terminal.has(body.data.status)) return body.data;

    await new Promise((resolve) => setTimeout(resolve, delay));
    delay = Math.min(delay * 2, 10000);
  }
}

The progress object includes the processing stage, percentage, and byte counts when the source provides them.

6. Download the result

When status is ready, the job contains:

artifact: filename, content type, and size
artifactExpiresAt: when the private artifact will be deleted
downloadUrl: a signed, temporary URL
downloadUrlExpiresAt: when that particular URL expires

The signed URL normally lasts five minutes and supports GET, HEAD, and single HTTP byte ranges. If the URL expires while the artifact still exists, call GET /api/v1/downloads/{id} again to receive a new URL.

curl -L "$SIGNED_DOWNLOAD_URL" --output result.mp4

Download or copy the artifact to your own durable storage promptly. ADownload's artifact storage is intentionally temporary.

List and cancel jobs

List up to 50 recent jobs:

curl "$DOWNLOADER_BASE_URL/api/v1/downloads?limit=20" \
  -H "Authorization: Bearer $DOWNLOADER_API_KEY"

Cancel an active job:

curl -X DELETE "$DOWNLOADER_BASE_URL/api/v1/downloads/JOB_ID" \
  -H "Authorization: Bearer $DOWNLOADER_API_KEY"

Cancellation is idempotent. The API returns the current job if it is already terminal. Reserved balance is restored when cancellation reaches the processing service.

Errors and retries

Errors use a stable envelope:

{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "Economy downloads support up to 720p"
  }
}

HTTP status	Typical code	What to do
401	`unauthorized`	Replace or re-enable the API key
402	`insufficient_credits`	Top up the USD balance, then submit with a new key
409	`idempotency_conflict`	Reuse the original body or generate a new key
413	`request_too_large`	Keep the JSON body below 16 KiB
422	`invalid_request`	Correct the request fields or source URL
429	`too_many_requests`	Wait for the `Retry-After` duration
503	`service_unavailable`	Retry with backoff and the same idempotency key

Do not retry 401, 402, 409, or validation errors automatically. Network failures, 429, and 503 may be retried with backoff. Preserve the same idempotency key for ambiguous create responses.

Source and safety policy

ADownload is for media that is public and that you are authorized to download. “1,000+ platforms” describes extractor coverage, not permission to download or a guarantee for every URL. The service does not accept cookies or login sessions and does not bypass DRM, geographic restrictions, access controls, or source rate limits. Playlists and live streams are rejected. A source may stop working when its public interface changes; inspect the job's error.code and error.message.

Optional local Codex Skill

In addition to remote MCP, Codex can install the downloader-agent Skill and use its local CLI against the same /api/v1 REST API. Configure the Skill with the site origin and an API key:

export DOWNLOADER_API_URL="$DOWNLOADER_BASE_URL"
export DOWNLOADER_API_KEY="sk_..."

The Skill creates jobs, polls them, checks the balance, downloads completed artifacts, and cancels jobs. Other third-party agents use the MCP endpoint above; human developers can use the REST examples directly.

Versioning

The /api/v1 path is the stable public contract. Backward-compatible fields may be added without changing the version. Removing or changing existing fields requires a new major API path. Use capability discovery instead of hard-coding limits when possible.

For generated clients and API tooling, import the OpenAPI 3.1 document.