REST API and embed widget
On this page
Other programs can use your downloader in two ways. The REST API answers an app or a script that shows an API key: one request returns the title, the picture and every format with its download link. The embed widget puts a small download box on a partner's website.
Switching the API on
Admin → Settings → REST API:
| Label | Key | Default |
|---|---|---|
| Enable public REST API | api_enabled | off |
| Requests per minute for a key you make | api_requests_per_minute | 60 |
| Requests per day for a key you make | api_daily_limit | 0 (unlimited) |
| Who may make API keys | access_api | Members (signed in) |
| Keys per member | api_member_keys | 3 (1 to 20) |
| Requests per minute for a member's key | api_member_per_minute | 20 |
| Requests per day for a member's key | api_member_daily | 200 |
| Show the page for developers | api_docs_public | on |
Who may make API keys offers Members (signed in), Members with a confirmed e-mail address or Nobody: only the keys you make yourself. Members' keys need member accounts (Member accounts).
Keys you make: Admin → API keys
Settings → API keys → New api key:
- Name: who uses it, for example "Mobile app".
- Allowed IP addresses: optional; requests from other addresses are refused.
- Requests per minute and Requests per day: empty uses the defaults above, 0 means unlimited.
- Active.
The full key (it starts with aio_) is shown once, right after you save. Copy it then; the site keeps only a fingerprint of it.
The list shows every key, yours and the members': Name, Owner (Admin or the member's e-mail), the first characters of the Key, Today, Requests, Last used and Active. You can give a member's key limits of its own or switch it off.
Members' own keys: Account → API
When members may have keys, their account gets an API page: a name, Create key, the new key shown once, today's use of each key and Delete. A member has at most Keys per member keys. A key stops working as soon as its owner may not have keys any more: suspended, no longer allowed by the rule, or deleted.
The endpoints
| Request | Answer |
|---|---|
GET /api/v1/info?url=… | one link: title, thumbnail, duration, author, the results page and every format |
GET /api/v1/playlist?url=…&limit=… | the entries of a playlist, each with its own info address |
GET /api/v1/me | the key that asks: its limits and what is left of today (not counted) |
GET /api/v1/platforms | the supported sites; no key needed |
/api/v1/download is the older name of /api/v1/info and keeps working. info also takes track, the id of a dubbed sound track of a YouTube video.
The key travels in the header X-API-Key (or Authorization: Bearer …, or ?api_key=):
curl -H "X-API-Key: aio_xxxxxxxxxx" "https://your-site/api/v1/info?url=https://youtu.be/aqz-KE-bpKQ"Each format in medias carries type, quality, ext, codec, size, has_audio, url (the source) and download (the link through your site, which also joins split video and sound). Blocked URLs, disabled platforms and your download settings apply as on the site.
Limits and errors
A failed answer has "ok": false, a short error code and a message:
| Status | error | Meaning |
|---|---|---|
| 401 | unauthorized | no key, or a key that does not exist |
| 403 | forbidden, api_disabled | wrong IP address, an owner who may not use the API, or the API is off |
| 422 | invalid_url, unsupported_site, no_media, not_found, playlist_link | nothing to download behind the address (a playlist link belongs to /api/v1/playlist) |
| 429 | rate_limited, quota_exceeded | too many requests this minute, or the day's number is used up |
| 502 | blocked | the source turned the server away |
A key with a daily limit gets X-RateLimit-Limit and X-RateLimit-Remaining in every answer; after a minute limit the answer carries Retry-After: 60. Daily numbers start again at midnight UTC.
The page for developers
With Show the page for developers on, /en/developers (in every language) explains the API to the people who use it: getting started, the key, requests and answers, errors, limits, and examples in cURL, PHP, JavaScript and Python. A link to it sits in the footer. Visitors read how to get a key: create a free account, or ask you when members may not have keys.
The embed widget
Settings → Embed Widget:
- Enable embeddable widget (
embed_enabled, off). - Widget requests per minute per visitor (
embed_rate_limit, default 30). - Default widget theme: Light or Dark.
- Show "Powered by" link.
Only websites you list may use it: Settings → Embed widget → New website:
- Name, and Website origin such as
https://example.com(scheme and host, no path), or an Origin pattern (advanced): a regular expression for several origins, e.g.#^https://([a-z0-9-]+\.)?example\.com$#. - Theme, Accent colour and Active.
- What this website shows: Show thumbnail, Show title, Video downloads, Audio downloads, Show "Powered by", and Fetch automatically when a URL is passed (off by default).
The partner pastes this where the box should appear:
<div data-aio-widget data-theme="light"></div>
<script src="https://your-site/embed.js" async></script>Optional attributes: data-url (a link to fill in), data-theme (light or dark), data-accent (#rrggbb), data-lang (en, bn ...) and data-auto-fetch="1", which works only when the website has Fetch automatically when a URL is passed on. An attribute wins over what you saved for the website; leave data-theme out to use the saved theme. The box grows with its content, and the partner's page can listen for a message of type aio:result.
The list counts the Requests per website. Downloads from the widget go through your site, so your countdown, limits and shortener apply.