Why TikTok API pull_from_url Domain Verification Rejects Your Host

What is TikTok API pull_from_url domain verification?

Passing TikTok API pull_from_url domain verification means TikTok has confirmed that you control the host serving your media file, and until that confirmation exists no file is ever fetched. It is an ownership check on the URL, not on the video, and it happens before TikTok's downloader opens a single connection.

The check applies to every init call that carries source: "PULL_FROM_URL":

Photos have no alternative. The photo endpoint states that "Only PULL_FROM_URL is allowed" in source_info.source, so verification is not an optimisation for photo posting, it is the entire prerequisite. Videos can bypass it by switching to FILE_UPLOAD, though TikTok's Content Sharing Guidelines push the other way: "If video resources are already on API Clients' servers, do not use FILE_UPLOAD; use PULL_FROM_URL instead."

How do you verify a domain with TikTok?

You add the host as a property on your app, then prove control of it through DNS. TikTok's Media Transfer Guide describes the flow in one sentence:

"To confirm ownership, log into the TikTok for Developers website and add your Domain or URL Prefix property to your application in the URL properties widget as shown below. You must have manage or write access to the property."

On the method itself, TikTok writes: "To verify domain ownership, it is recommended that you add a signature string to the domain's DNS records." The word "recommended" implies a second route exists, and TikTok documents none. There is no published HTML meta tag method, no file-upload method, no record type named, no TTL guidance, and no statement of how long propagation is allowed to take or whether TikTok rechecks the record later. If your DNS is delegated to a provider you do not control, that undocumented gap is the thing that blocks you, and the docs offer no fallback.

The mechanic itself is the same one behind a custom domain handle on Bluesky: a string in a DNS record proves that whoever asked for the verification also runs the zone.

How far does a verified domain reach?

Downward, never upward. TikTok states the rule and then gives the example that makes it concrete:

"Once the ownership of a domain is verified, all paths under that domain or its subdomains are considered owned by the developer application."

"For example, if you have verified the domain static.example.com, then URLs like https://video.static.example.com/tiktok/example.mp4 are considered verified, while URLs like https://example.com/videos/example.mp4 are still considered unverified."

Read that second half again, because it is the trap. Verifying a subdomain does not verify the parent. A team that verifies cdn.example.com and then moves assets to example.com/cdn/ loses verification entirely, even though the organisation obviously still owns both. The apex domain is a separate property and needs its own record.

URL Prefix properties are narrower still, and TikTok defines the shape precisely: "A URL prefix consists of: https:// + host + path + /." The host "must be a domain and should not be an IP address", and matching is literal:

"For example, if you have already verified the domain https://example.com/videos/user/, then URLs like https://example.com/videos/user/123/example.mp4 are considered verified, while URLs like https://example.com/videos/2023/user/123/example.mp4 are still considered unverified."

Note that TikTok calls a URL prefix "the domain" in its own prefix example. The wording is loose, the behaviour is not: inserting 2023/ between videos/ and user/ produces a string that no longer starts with the verified prefix, and the request fails. Any storage layout that puts a date, a tenant ID or a shard number ahead of the verified segment will fail the same way, which is a good argument for verifying the domain rather than a deep path.

What are the other pull_from_url rules?

Three conditions sit alongside ownership, and TikTok states each one flatly.

The scheme is fixed: "The media URL must use "https" and should not redirect to another URL." The prefix rules are blunter about what happens if it does: "Redirections are not followed. URLs that return HTTP 3xx are considered invalid." A signed-URL service that answers with a 302 to storage, or a CDN that bounces the request one hop, is invisible to a browser test and fatal here. This is one of the few places where a redirect chain is not a performance footnote but an outright failure.

The URL has to stay alive for the whole job: "The URL must remain accessible for the entire duration of the download process, which times out one hour after the download task is initiated." Short-lived signed URLs need a lifetime longer than an hour, not longer than a few minutes.

Bandwidth has a stated ceiling: "TikTok server's ingress bandwidth for file downloads can reach 100 Mbps." TikTok publishes no minimum, so a rate-limited origin simply runs the clock down until the one-hour timeout ends the task.

TikTok also publishes one escape hatch for testing. The Media Transfer Guide links a sample MP4 on its own CDN and notes that you can try it "without any verification", which lets you exercise the full init and status flow before your DNS record exists.

What does the url_ownership_unverified error look like?

An unverified host returns HTTP 403 with error.code set to url_ownership_unverified. The interesting part is that TikTok describes the same code three different ways on three live pages:

"Video transfer method", "content transfer method" and "media transfer method" are the same mechanism under three names. Match on the code string, never on the message. The third row is stranger than the wording: url_ownership_unverified appears in the documented response spec for /v2/post/publish/cancel/, an endpoint that takes only a publish_id and no URL at all. TikTok does not explain how a cancel request can fail an ownership check, and the field list gives it no way to.

Verification passing is not the same as the download succeeding. Once ownership clears, failures move downstream into the fail_reason returned by /v2/post/publish/status/fetch/, where video_pull_failed and photo_pull_failed share one description: "The TikTok server encountered a connection error while downloading the specified video resource, or the download is terminated since it can not be completed within the one-hour timeout." Format and size problems arrive separately as file_format_check_failed or picture_size_check_failed, in the same spirit as Instagram's image requirements rejecting a file that uploaded perfectly well.

One field is worth setting in the same request. is_aigc marks synthetic media at post time, and the two flavours of the TikTok AI generated label behave very differently depending on whether you set it or TikTok infers it.

Frequently asked questions

Does verifying example.com also verify cdn.example.com?

Yes. TikTok states that "all paths under that domain or its subdomains are considered owned by the developer application", so a verified apex covers its subdomains. The reverse fails: verifying cdn.example.com leaves example.com unverified.

Can I use an IP address or a plain http URL?

No to both. TikTok requires that "The media URL must use "https"", and the URL prefix definition states that the host "must be a domain and should not be an IP address."

Why does my signed S3 or Cloud Storage URL fail verification?

Usually because the bucket host is not a property on your app, or because the signed URL answers with a redirect. TikTok does not follow redirects and treats any HTTP 3xx response as invalid, so the hop to the storage backend ends the attempt.

How many photo URLs can one request carry?

Up to 35. The photo endpoint describes photo_images as "An array containing up to 35 photo content URLs. The URLs must be publicly accessible and verified by your app", and every one of those URLs is subject to the same ownership check.

Does the one-hour window start at init or at first byte?

At task start. TikTok says the download "times out one hour after the download task is initiated", so a slow origin burns the same clock as a large file, and the task ends in video_pull_failed rather than waiting.

Can I cancel a download that is already running?

On a best-effort basis. /v2/post/publish/cancel/ takes the publish_id, and TikTok warns that "it is not feasible to cancel downloads that are nearing completion or already in the file processing state." A successful cancel surfaces later as the publish_cancelled fail reason.

Can I skip TikTok domain verification altogether?

Only if you are posting video. Switching the transfer method to FILE_UPLOAD removes the ownership check, though TikTok's own Content Sharing Guidelines push against it for video already sitting on your servers. Photos have no such option: the photo endpoint allows only PULL_FROM_URL, so verification is mandatory there.

Does TikTok let me test PULL_FROM_URL before my DNS record exists?

TikTok publishes exactly one escape hatch for this. The Media Transfer Guide links a sample MP4 hosted on its own CDN and says it works "without any verification", so you can run the full init and status flow before adding a DNS record. It only covers that one file, not your own media.

How fast does TikTok download the file from my URL?

Up to the ceiling TikTok states: 100 Mbps of ingress bandwidth for file downloads. TikTok publishes no minimum speed for your origin, so a rate-limited server just lets the one-hour clock run down until the task ends in video_pull_failed or photo_pull_failed.

What's the difference between url_ownership_unverified and video_pull_failed?

url_ownership_unverified is the upfront check: TikTok rejects the init call with HTTP 403 before it ever opens a connection to your URL. video_pull_failed, and its photo counterpart photo_pull_failed, shows up later, after ownership already cleared, when the download itself hits a connection error or runs past the one-hour timeout.