Normalizing pasted links: expanding vt.tiktok.com and youtu.be before resolving

Most people never paste a clean link into a downloader. They paste whatever the share button gave them: a short link from the app, a link with tracking junk stuck on the end, or a link they copied half-heartedly from the address bar. If my server sent that string straight to the provider, half of those pastes would fail, and the visitor would blame the tool. So before ramrom.io spends a single API call, it normalises the link. That one small step fixed more failed downloads than anything else I have built on the site.

The short links are the biggest problem. TikTok shares as vt.tiktok.com links, YouTube shares as youtu.be, Instagram shares as instagram.com/reel/... — but a share from inside the app can also be a vm.tiktok.com or a www.tiktok.com link with a dozen tracking parameters. These are all the same video, but to a provider API they look like different requests, and some providers simply refuse short links outright. They expect a canonical URL, and they will not expand the short one for you.

The fix is boring, which is why I like it. On the server, in PHP, I take the pasted string, trim it, and check the host. If it is a known short domain — vt.tiktok.com, vm.tiktok.com, youtu.be, youtube.com/shorts links that still carry a share id — I send a HEAD request to it with redirects followed and a short timeout, then read the final URL after the redirect chain. That final URL is the canonical one. I never fetch the page body; a HEAD request is enough, and it keeps the whole thing fast.

I cap the redirect chain at five hops, the same limit I use in the download proxy. A short link should resolve in one or two hops. If it takes more than five, something is wrong — a redirect loop, a tracking service that bounces the link around — and I stop and tell the visitor the link could not be read. That is better than hanging the page while curl chases its own tail.

Then I clean what is left. Tracking parameters come off: ?si= on YouTube, ?igshid= on Instagram, the utm_ parameters on everything. None of them identify the video; they identify where the link was shared from. Stripping them does not change the video, but it does two useful things. First, it stops the provider from choking on a parameter it does not expect. Second, it means the same video pasted by two different people normalises to the same URL, which makes caching and logging actually meaningful — I can see that a link was resolved before without storing anything about who pasted it.

There is one more check, and it happens before any of this. I validate that the host belongs to a platform I support: TikTok, Instagram, Facebook, or YouTube. If someone pastes a link from somewhere else, I say so straight away — "this site only handles TikTok, Instagram, Facebook and YouTube links" — instead of sending a doomed request to a provider and then reporting a confusing error. Validating first also saves quota: every provider call costs money on the free tier, and a link that could never work should never cost one.

None of this is clever. There is no machine learning, no database, no framework. It is a few dozen lines of PHP: trim the input, expand the short host, strip the tracking parameters, check the host is supported, and only then call the provider. The code lives in resolve.php, the same endpoint that does the API call, so the two steps can never drift apart.

The lesson I keep relearning on this project is that the paste is the interface. Visitors do not read instructions about which link format to use; they paste what they have. A tool that only accepts clean links is a tool that fails for real people. Normalising the link first — quietly, without asking the visitor to do anything — is the difference between a downloader that works and one that looks broken for reasons nobody can explain.