Providers — Introduction

Moonez.ai is a neutral routing platform: clients create generation jobs, and providers (compute partners) pull those jobs, generate images/text with their own Google keys and proxy fleet, and push results back.

As a provider you never share your Google keys with us. You keep your own infrastructure (engine + keys + proxies) and talk to the platform over a simple HTTP API. The platform only ever receives connections from you — it never connects out to your infrastructure.

How to become a provider

1. Register — call POST /api/v1/provider/register with your organization name and contact. Your account is created in pending state.
2. Verification (KYB) — our team verifies you in the admin panel (contract/KYC, capacity, models you can serve). Once approved, you receive a provider token (issued once, prefix pv_) and your limits (RPM/RPD, max daily amount, allowed models, IP whitelist).
3. Pull jobs — authenticate with the token and start pulling queued jobs.
4. Submit results — generate with your engine, upload the result to our S3 via a presigned URL (or send a direct URL), and report the outcome.

Note The token is shown only once at verification time. Store it securely — it is the only credential that identifies you. If lost, ask the admin to regenerate it (the old one stops working immediately).

Provider responsibilities

• Complete each pulled job before its deadline. Jobs that miss the deadline are automatically requeued and handed to another provider.
• Respect your RPM/RPD limits — the API returns 429 when exceeded.
• If you are IP-whitelisted, all API calls must come from an allowed IP/CIDR (403 otherwise).
• Report failures honestly with a meaningful error_code/error_message — they are surfaced to the client (censored results, quota issues, etc.).

What you get in a job

Each pulled job carries:

Field	Description
job_id	UUID of the job — use it when submitting the result
model	Model to run (e.g. gemini-2.5-flash-image)
prompt	The generation prompt
resolution / aspect_ratio	Output dimensions (may be empty for text jobs)
attachments	Presigned GET URLs for input files (image-to-image), valid ~1 hour
price	Platform price for this job (decimal)
deadline_at	Absolute deadline (UTC) — finish before this or the job is requeued
timeout_seconds	Timeout budget for the request

API surface

Method	Endpoint	Auth	Purpose
POST	/api/v1/provider/register	—	Create a provider account (pending)
GET	/api/v1/provider/me	Bearer	Your own profile, status and limits
POST	/api/v1/provider/jobs/pull	Bearer	Pull up to N queued jobs (atomic claim)
POST	/api/v1/provider/jobs/{job_id}/result	Bearer	Submit the result (success/failed)

All endpoints are under the platform API base URL (e.g. https://api.moonez.ai).