Skip to content

docs: add guidance for time-limited URL expiration in download errors #838

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
agalyanmann wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add guidance for time-limited URL expiration in download errors #838

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions fern/pages/faq/async/what-types-of-audio-urls-can-i-use-with-the-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,8 @@ Alternatively, you can host your files elsewhere. Common approaches are to:
- Cloud storage services (GCP/Azure/AWS)
- Any direct download URL that serves audio/video content

<Note>
**Time-limited URLs must be fresh at submission time.** If you use presigned URLs (AWS S3, GCP, Azure SAS tokens) or CDN URLs from platforms like TikTok or Instagram, generate the URL immediately before submitting your request to `/v2/transcript`. If the URL expires before AssemblyAI downloads the file, the transcription will fail with a download error. For more details, see the [Troubleshoot Common Errors](/docs/guides/common_errors_and_solutions) guide.
</Note>

API Reference: [Upload endpoint](/docs/api-reference/files/upload)
9 changes: 9 additions & 0 deletions fern/pages/guides/cookbooks/core-transcription/common_errors_and_solutions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,6 +171,15 @@ Our API requires a publicly accessible URL that points to an audio file to retri
- **Direct Upload**: Utilize the [AssemblyAI Upload endpoint](https://www.assemblyai.com/docs/api-reference/upload) to upload files directly from your device, eliminating the need for a public URL.
- **AWS S3 Pre-signed URLs**: [This Cookbook](https://github.com/AssemblyAI/cookbook/blob/master/core-transcription/transcribe_from_s3.ipynb) shows you how to use pre-signed URLs for AWS S3 storage to provide secure, temporary access for transcription without making your files public.

<Note>
**Time-limited URLs (presigned URLs, CDN tokens, etc.) must be fresh when you submit them.** URLs from services like AWS S3 presigned URLs, Azure Blob Storage SAS tokens, GCP signed URLs, and social media CDNs (e.g., TikTok, Instagram) expire after a set duration. If the URL expires before AssemblyAI downloads the file, the origin server returns a `403` or `404` and you will see this download error.

To avoid this:
1. Generate the time-limited URL immediately before submitting your transcription request — do not cache or store URLs for later use.
2. Ensure the URL expiration window is long enough for the file to be downloaded (at least a few minutes).
3. If you cannot control the URL lifetime, use the [Upload endpoint](/docs/api-reference/files/upload) to upload the file directly to AssemblyAI instead.
</Note>

#### Audio File Errors

##### Attempting to transcribe audio files that are too short
Expand Down
Loading