FARPY documentation

What FARPY does

FARPY is a GPU execution and artifact-delivery service. The current public product uploads Blender .blend files, renders them with Blender Cycles on GPUs, delivers the result as a ZIP and generates a USD receipt with output SHA-256 proof.

Public API workflow

• 1. Get current capabilities, pricing and limits.
• 2. Create an API key from Account Settings.
• 3. Upload the .blend file.
• 4. Preflight the request when you need eligibility feedback before submission.
• 5. Submit the render with an idempotency key.
• 6. Poll status or receive a signed terminal webhook.
• 7. Download the artifact and retrieve its receipt and proof.

Authenticated request example

• Set FARPY_API_KEY in the environment instead of placing the secret in source code.
• Send Authorization: Bearer $FARPY_API_KEY on authenticated render requests.
• Example: curl -sS https://farpy.com/v1/workspace/renders -H "Authorization: Bearer $FARPY_API_KEY"
• A 401 response means the key is missing, invalid or revoked.

Python client

The dependency-free Python 3 client uses only the standard library. FarpyClient.render(...) handles upload, submission, status polling, download, receipt and proof retrieval in one call. The granular methods remain available when you need custom control.

Authentication and key safety

• API render requests use a bearer API key.
• API keys are created, listed and revoked from the signed-in account.
• The secret key value should be treated like a password and never embedded in public client-side code.
• Revoke a key immediately if it is exposed or no longer needed.
• API keys cannot create topups or manage the account.

Idempotency

Use a stable idempotency key when submitting a render. If a network failure leaves the client unsure whether submission succeeded, retry with the same key instead of creating a new one. This prevents accidental duplicate jobs and double reservations.

Rate limits and retries

• Current limit: 60 requests per minute per client plus a burst of 20.
• HTTP 429 means the client should slow down.
• Rate-limit responses include Retry-After and retry_after_seconds.
• Retry transient network, 502 and 504 failures with bounded backoff.
• Do not blindly retry validation, authentication, balance or permanent job failures.

Error responses

Error responses include error.code and error.message. Request identifiers are not currently guaranteed. Use the HTTP status, error code, message and retry timing to decide whether to fix, retry or stop.

Job status and terminal states

• Poll the render status endpoint until the job reaches a terminal state.
• Completed means the output, receipt and proof can be retrieved.
• Failed means execution ended without a completed artifact; preserve the job_id and returned error details.
• Cancelled means the accepted cancellation ended the job before completion.
• Do not infer completion from elapsed time, webhook delivery or a successful submission response.

Cancellation

A render can be cancelled before a worker claims it. After execution has begun, the cancel request may be rejected. Check the returned status instead of assuming cancellation succeeded.

Signed webhooks

• Terminal events: render.completed, render.failed and render.cancelled.
• Webhooks are signed so the receiver can verify the sender.
• Use HTTPS and verify the signature before trusting the payload.
• Treat duplicate delivery as normal and handle events idempotently.

Downloads, receipts and proof

A completed job produces a downloadable ZIP artifact, a canonical USD receipt and proof including the output SHA-256. The receipt documents the charge and job facts. The proof lets a client compare the downloaded output against the recorded hash.

Retry decision guide

• Retry HTTP 429 only after the supplied Retry-After or retry_after_seconds delay.
• Retry temporary network, HTTP 502 and HTTP 504 failures with bounded exponential backoff.
• Reuse the same idempotency key when retrying an uncertain submission.
• Do not retry HTTP 400 validation failures until the request is corrected.
• Do not retry HTTP 401 until the API key is supplied or replaced.
• Do not continuously retry a terminal failed or cancelled render.

Failure recovery

• Upload rejected: confirm the file is a .blend, under 100 MiB and uses Cycles.
• Preflight rejected: fix the returned validation errors before submission.
• Uncertain submission: retry with the same idempotency key.
• Rate limited: wait for the provided retry timing.
• Job failed: read the terminal status and preserve the job id for support.
• Download mismatch: do not trust the file; compare its SHA-256 with the proof and redownload.

Known limits

• The public rendering lane currently supports Blender Cycles only.
• Maximum upload size is 100 MiB.
• Maximum frame count is 10,000.
• Cancellation is only guaranteed before worker claim.
• Request identifiers are not guaranteed in error responses.
• Capabilities, pricing and limits are separate machine-readable endpoints.

Support and diagnostics

For support, preserve the job_id, receipt_id, account email, timestamp, idempotency key and the exact error code or message. Do not send an API key, session cookie or other secret.

Canonical references

• API overview: /api/
• Agent integration guide: /api/agent-rendering/
• Developer quickstart: /developers/quickstart/
• API error guide: /developers/errors/
• Webhook guide: /developers/webhooks/
• OpenAPI 3.1 contract: /v1/openapi.json
• Python client: /farpy_client.py
• Python example: /farpy_client_example.py
• Pricing: /pricing/
• Status: /status/
• Proof: /proof.html