Base address and authentication
All endpoints live under https://ugesi.com/api/. Send your key as: Authorization: Bearer ugsk_your_key. A missing or revoked key returns 401.
MCP and ChatGPT Actions
Claude and Cursor: run mcp/server.js with your key. ChatGPT: point an Action at /.well-known/openapi.json. Four operations: list models, generate, job status, recipe.
Start a generation
POST /api/generate/ with a JSON body containing tool, model, prompt and any required input URLs. The response returns 202 with a job id and the credits held for the run.
Check a job
GET /api/jobs/?id=JOB_ID returns the status: queued, running, succeeded or failed. A failed job releases its credits automatically, so there is nothing to reconcile.
Get the result
A finished job carries a signed URL to the output file. The link expires, so download rather than hotlink it into your product.
Webhooks instead of polling
Send a webhook_url with the request and we call it once the job settles. This is the recommended pattern above a few requests per minute.
Models and rates
GET /api/models/ returns every model with its slug, unit and current rate in credits. Read it at deploy time rather than hardcoding rates.
Errors
400 for a malformed body. 401 for a bad key. 402 when the balance is short. 403 outside Enterprise. 404 for an unknown tool. 422 for a missing input. 429 over the rate limit.
Rate limits
Sixty requests per minute per key by default. The 429 response includes Retry-After in seconds. Back off rather than retrying immediately.