DEVELOPER DOCS
Spoofzy API
Build automations, internal tools, and team queues with Unlimited Spoofer as one reliable processing step.
API fair use: plan-included Unlimited processing allows 2,000 output files per account per UTC day, shared across keys, MCP, workflow hooks and schedules. Batches reserve their output count when accepted; polling and exact retries do not count again. Paid Credits and prepaid Spoofer units retain their allowances.
https://api.spoofzy.com/api/v1
00
Quick start
Sign in to Cloud and create a key with Read Cloud jobs and results (jobs:read). In your terminal, run export SPOOFZY_API_KEY='YOUR_KEY' with your own key. This request lists the tools available to your account and costs no Credits.
curl --fail-with-body \
-H "Authorization: Bearer $SPOOFZY_API_KEY" \
https://api.spoofzy.com/api/v1/capabilities
To run a Cloud tool, request an upload with POST /uploads, submit POST /jobs with an exact, reusable request_id, and poll GET /jobs/{job_id}. See the OpenAPI reference for request fields.
01
Create a prepaid Spoofer upload
The /spoofer examples use an active prepaid allowance. Use prepaid:write to submit and prepaid:read to check results. Existing prepaid keys from Telegram also work. Send the original filename and content type to get a short-lived upload URL.
curl -X POST "https://api.spoofzy.com/api/v1/spoofer/uploads" \
-H "Authorization: Bearer $SPOOFZY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filename":"source.jpg","content_type":"image/jpeg"}'
02
Upload the file
PUT the source file to upload.url. Use the exact Content-Type returned in upload.headers.
curl -X PUT "$UPLOAD_URL" \
-H "Content-Type: image/jpeg" \
--upload-file ./source.jpg
03
Create a job
Use a new opaque idempotency key for each request. Reuse it only when retrying the exact request. For advanced video processing, use the batch endpoint below with variants: 1 for one output.
curl -X POST "https://api.spoofzy.com/api/v1/spoofer/jobs" \
-H "Authorization: Bearer $SPOOFZY_API_KEY" \
-H "Idempotency-Key: 7a0a32f8-customer-file-001" \
-H "Content-Type: application/json" \
-d '{"upload_id":"upl_…","filename":"source.jpg"}'
One Spoofer mode
Your account selects the processing profile. Send the source and output count; no mode, preset or algorithm version is required. Video batches on an account assigned extreme-fitted-fast-v2 always use that profile.
Existing standard, minimal and text_preserving preset values remain accepted as compatibility labels for new requests. They no longer select different algorithms. Exact retries of previously accepted requests return the original job or batch without processing or charging again. Bot preferences are not inherited.
If the assigned worker is unavailable, the API returns 503 before charging. It never silently substitutes another video profile.
04
Poll the job
Poll until job.status is completed or failed. A completed job includes a temporary result.download_url. A failed job returns its reserved credit automatically.
curl "https://api.spoofzy.com/api/v1/spoofer/jobs/$JOB_ID" \
-H "Authorization: Bearer $SPOOFZY_API_KEY"
One upload, many variants
Use upload_id, filename and variants for account-default video processing. No processing options or worker-version parameter is required. Explicitly enabled accounts can request up to 300 variants; GET /api/v1/spoofer/account reports your balance, batch limit, concurrency and assigned processing_profile.
curl -X POST "https://api.spoofzy.com/api/v1/spoofer/batches" \
-H "Authorization: Bearer $SPOOFZY_API_KEY" \
-H "Idempotency-Key: YOUR-PERSISTED-UNIQUE-REQUEST-ID" \
-H "Content-Type: application/json" \
-d '{"upload_id":"upl_…","filename":"source.mp4","variants":100}'
Keep this request shape, endpoint and key when your account capacity or assigned worker changes. Set the output count within your account limits; legacy preset values remain accepted and cannot change the assigned profile.
The whole batch reserves one output unit and one concurrent slot per variant. A 429 spends nothing. Reuse the exact request and key after a lost response; changing parameters returns 409.
Optional export settings include device_stamping (off, iphone15pro_v1 or iphone16pro_v1), and output_size (original, 1080p or 4k). Device stamps are synthetic export metadata. Unavailable processing options return 503 before charging.
Poll GET /api/v1/spoofer/batches/{id} every 10 seconds. Status is processing, completed, partial or failed. Each result has a stable zero-based index. Failed outputs refund their units once; successful outputs remain charged. Download completed files promptly.
Check GET /api/v1/spoofer/account for your remaining outputs, batch and concurrency limits, expiry and processing_profile. For video batches, omitting options uses the assigned profile. On an account enabled for extreme-fitted-fast-v2, the simple request above selects that profile automatically. Legacy preset labels use the same profile. Use batches with variants: 1 for a single improved output. Keep original size, mirror off, device stamping off, and account watermarks and captions off. Unsupported advanced-profile options fail before charging; an unavailable advanced worker never silently falls back to Standard. Batches can take several minutes and may return fewer qualified outputs with the remainder refunded.
Link the Telegram account that owns your prepaid allowance to see its balance, runs and downloads in Cloud. A scoped API key with prepaid permissions can use that allowance.
Optional completion event
Add completion.url (public HTTPS) and a separate random 32–128 character completion.secret. Verify the HMAC-SHA256 signature and timestamp against the raw request body, durably deduplicate the event ID, then return 2xx and fetch results. Delivery can repeat; a failed webhook never reprocesses the batch.
The machine-readable guide includes signing, retries and failure handling. Account limits and measured worker capacity determine throughput. Perceptual hash differences do not establish Instagram or Facebook acceptance.
05
Limits and safety
- Images
- JPG, PNG, and WebP up to 100 MB
- Video
- MP4, M4V, and MOV up to 300 MB
- Retention
- Job records: 30 days. Batch receipts and temporary files: 7 days.
- Delivery
- Polling; signed completion events for enabled batches
All scoped keys on an account share 45 requests per minute. Your prepaid plan also sets how many variants can process at once. Check the error code on a 429 response and follow Retry-After when present.