# Spoofzy API > Add Unlimited Spoofer to an automation, internal tool, queue, or team workflow. Upload an image or video, create a job, then poll for a temporary download URL. ## Use this API safely - Keep the customer's Bearer key in a server-side secret store. Never place it in browser JavaScript, a mobile app, prompts, logs, or source control. - Use the upload URL only with the content type returned by the API. - Send a new opaque Idempotency-Key for each source file. Reuse that same key only when retrying the exact request. - Single jobs use polling until `completed` or `failed`. Explicitly enabled batch accounts can use signed completion webhooks. - A failed job returns its reserved job unit automatically. - Plans are measured in completed jobs, not raw HTTP requests. - Plan-included Unlimited processing has a fair-use cap of 2,000 output files per account per UTC day, shared across API keys, MCP, workflow hooks and schedules. Batch outputs are reserved at acceptance; exact retries and polling do not consume more. Paid Credits and prepaid Spoofer units retain their allowances. HTTP 429 api_fair_use_limit includes Retry-After until 00:00 UTC; GET /capabilities includes fairUse usage and reset time. ## Discovery - Human docs: https://api.spoofzy.com/api/docs - OpenAPI: https://api.spoofzy.com/api/openapi.json - API base: https://api.spoofzy.com/api/v1 - Get an API key: https://cloud.spoofzy.com/?panel=developers&tab=settings. Use GET /capabilities with jobs:read to discover Cloud tools. - Active prepaid Spoofer accounts can use that same key on /spoofer routes with prepaid:read for balance and results and prepaid:write for processing. Existing prepaid keys issued through https://t.me/SpoofzyBot?start=api still work on these routes. ## Prepaid Spoofer request sequence 1. POST /api/v1/spoofer/uploads with `filename` and `content_type`. 2. PUT bytes to the signed `upload.url` using the returned Content-Type. 3. POST /api/v1/spoofer/jobs with `upload_id`, `filename`, and Idempotency-Key. For an advanced video account, use /spoofer/batches with variants=1 even for one output. 4. GET /api/v1/spoofer/jobs/{job_id} until status is completed or failed. The API has one Spoofer mode, selected by the account. Omit options.preset. Existing standard, minimal and text_preserving values remain accepted as compatibility labels for the same account processing; they do not select separate algorithms. Exact retries retain the previously accepted result. Bot preferences are not inherited; account watermark and Caption Autopilot behavior is unchanged. An unavailable assigned worker returns 503 before charging. Supported source types: JPG, PNG, WebP (up to 100 MB); MP4, M4V, MOV (up to 300 MB). Job records are retained for 30 days. Batch receipts and temporary files retain their seven-day expiry; download results promptly. ## Opt-in batches GET /api/v1/spoofer/account reports units_remaining, active_jobs, concurrency_limit, batch_limit and expires_at. After uploading once, POST /api/v1/spoofer/batches with upload_id, filename, variants (1–300), and an Idempotency-Key. These three body fields are enough for account-default video processing. Keep the same /api/v1 endpoint, Bearer key and request shape when account capacity or the assigned worker changes; no worker-version parameter is required. Video batches use the account processing_profile, including extreme-fitted-fast-v2 when enabled. No preset selection is needed. Legacy preset values cannot downgrade that profile. Other optional settings are vertical_flip=false|true, device_stamping=off|iphone15pro_v1|iphone16pro_v1 and output_size=original|1080p|4k. Unsupported advanced-profile settings return 503 before charging. Device profiles are synthetic export metadata. Read batch_limit and concurrency_limit from GET /api/v1/spoofer/account; approved account limits determine whether one request can contain 100 or 300 outputs. The same source can supply every variant. A batch reserves one prepaid output unit and one active slot per variant atomically. Your approved account limits still apply; 429 reserves nothing. Retry the EXACT same parameters with the same key after a lost response. Changed parameters return 409. A new key requests another paid batch. Poll GET /api/v1/spoofer/batches/{batch_id} every 10 seconds. Status is processing, completed, partial or failed. The jobs array contains stable zero-based indices and individual results. Failed outputs refund their units once; successful outputs remain charged. Download the results promptly. Status reads refresh temporary download signatures but do not extend media retention. Optional completion: {"url":"https://your-public-host.example/spoofzy", "secret":"YOUR_RANDOM_32_TO_128_CHARACTER_SECRET"}. Events contain id, type=batch.finished, batch_id and status. Verify X-Spoofzy-Signature (v1=HMAC-SHA256 of ASCII timestamp + '.' + exact raw body), X-Spoofzy-Timestamp within 300 seconds, and X-Spoofzy-Event-ID against body.id. Durably deduplicate event IDs before acknowledging with 2xx. Then fetch results with your Bearer key. Webhook delivery can repeat and never restarts processing. Transient failures retry after 60, 300, 900, 3600 and 10800 seconds; redirects and permanent 4xx stop delivery. Polling remains available independently. No Instagram/Facebook detection or fixed batch-latency guarantee is implied. API keys and webhook signing secrets belong in separate server-side secrets.