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.

Base URL 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.

Keep the key private.Do not put it in browser JavaScript, a mobile app, prompts, logs, or source control.

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.

API resourcesMachine-readable copies of this contract.
OpenAPI 3.1LLMs.txt