Authentication
Private beta endpoints should use bearer API keys over HTTPS. Keep keys server-side and rotate them when team members or automation systems change.
Docs
Build media automation on top of SwiftTool.
SwiftTool API concepts for building automated media workflows around uploads, queues, AI processing, webhooks and secure result delivery.
API foundations
Designed for reliable long-running media jobs.
Job lifecycle
Most long-running media work is asynchronous: create a job, poll or receive a webhook, then download the finished output bundle.
Media safety
Use signed upload and download URLs for production deployments. Do not expose private cloud storage paths directly to public browsers.
Idempotency
Send an Idempotency-Key header when retrying job creation so network retries do not create duplicate processing jobs.
Workflow
One job lifecycle from upload to output.
Most SwiftTool actions can be queued, monitored and delivered through the same pattern.
Create or upload the source media file.
Submit a transcription, translation, separation or conversion job.
Track queued, processing, completed and failed states.
Download the output bundle or receive a completion webhook.
Endpoints
Core routes for media automation.
POST
/v1/transcribe
Create transcription job
Generate SRT, VTT, TXT or JSON captions from audio or video.
Request
- file or source_url
- language=auto or ISO language code
- outputs[]=srt|vtt|txt|json
- speaker_hints optional
Response
- job_id
- status
- estimated_seconds
- output_formats
Notes
- Use clean audio where possible.
- Long files should run through cloud workers.
- Review generated captions before publishing.
POST
/v1/translate
Translate subtitle file
Translate SRT or VTT files into 100+ languages while preserving timing.
Request
- subtitle_file
- source_language optional
- target_language required
- tone=natural|formal|short
Response
- job_id
- status
- source_language
- target_language
Notes
- RTL languages are supported.
- Subtitle timing is preserved.
- Human review is recommended for legal, medical or educational material.
POST
/v1/separate
Separate vocal stems
Split an audio file into vocals, drums, bass and instrumental stems.
Request
- file or source_url
- stems[]=vocals|drums|bass|other
- quality=standard|high
Response
- job_id
- status
- stems
- estimated_seconds
Notes
- Higher quality modes take longer.
- Use WAV for post-production workflows.
- Respect copyright and platform terms.
POST
/v1/convert
Convert media
Convert video, audio and caption files into publish-ready formats.
Request
- file or source_url
- format=mp4|webm|mp3|wav|vtt|srt
- quality preset optional
Response
- job_id
- status
- target_format
- download_url when ready
Notes
- Server limits should match nginx and PHP upload limits.
- Use webhook completion for batch processing.
GET
/v1/jobs/{id}
Inspect job status
Track queued, processing, failed and completed jobs.
Request
- job id in path
Response
- job_id
- status
- progress
- error
- outputs
Notes
- Poll every 5 to 15 seconds for active jobs.
- Prefer webhooks for production automation.
POST
/v1/webhooks/test
Test webhook delivery
Send a signed sample event to validate your automation receiver.
Request
- url
- event=job.completed|job.failed
- secret optional
Response
- delivered
- http_status
- latency_ms
Notes
- Verify signatures on your server.
- Respond with 2xx to acknowledge delivery.
Examples
Reference snippets for common integrations.
Create a transcription job
bashcurl -X POST https://swifttool.org/api/v1/transcribe \
-H "Authorization: Bearer $SWIFTTOOL_API_KEY" \
-H "Idempotency-Key: job-2026-06-27-001" \
-F "file=@interview.mp4" \
-F "language=auto" \
-F "outputs[]=srt" \
-F "outputs[]=vtt"Poll a job
bashcurl https://swifttool.org/api/v1/jobs/job_123 \
-H "Authorization: Bearer $SWIFTTOOL_API_KEY"Webhook payload shape
json{
"event": "job.completed",
"job_id": "job_123",
"status": "completed",
"outputs": ["captions.srt", "captions.vtt"],
"completed_at": "2026-06-27T10:00:00Z"
}Responses
Status codes to handle in production.
OK
Request succeeded and returned the requested resource.
Accepted
Job was accepted and is waiting in the processing queue.
Bad request
Input validation failed, required fields are missing or a format is unsupported.
Unauthorized
Missing, expired or invalid API credentials.
Payload too large
The uploaded file exceeds the configured plan or server limit.
Rate limited
Too many requests or too many concurrent jobs for the current plan.
Server error
Unexpected failure. Retry with the same idempotency key or contact support.
Production checklist
Before using the private API publicly, configure HTTPS, upload limits, signed URLs, webhook signature verification, API key rotation and monitoring for failed jobs.
Need a specific endpoint?
Use the support form for API access, custom workflow planning, private cloud workers or editor integration requests.
Contact support