API Spec

Public API contract

The public gateway exposes one model catalog, OpenAI-compatible chat, async media tasks, and compatibility routes for existing clients.

Authentication

Protected endpoints accept API keys through Authorization: Bearer. During migration, x-api-key remains available for old clients.

Accepted headers

Authorization: Bearer sk-your-api-key
x-api-key: sk-your-api-key

Errors

Error response

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits",
    "request_id": "req_123"
  }
}

400	invalid_json	Request body is not valid JSON.
400	missing_model	The request did not include a model id.
400	invalid_callback_url	The callback_url must be a public HTTPS URL.
401	auth_error	The API key is missing, inactive, or invalid.
402	insufficient_credits	The account does not have enough credits for the estimated request.
402	api_key_budget_exhausted	The project API key has reached its credit budget.
403	model_not_allowed	The API key is not allowed to call this model.
404	model_not_found	No active public model matches the requested id.
429	rate_limit_exceeded	The API key exceeded its per-minute request limit.
502	service_unavailable	No eligible upstream channel completed the request.

Endpoint contracts

GET	/api/v1/models	Returns active models with type, capability, pricing, and parameter metadata.
POST	/api/v1/chat/completions	Accepts OpenAI-compatible messages and returns OpenAI-compatible chat completions.
POST	/api/v1/images/generate	Creates an async image task and reserves credits before upstream processing.
POST	/api/v1/video/generate	Creates an async video task and returns a task id for polling.
GET	/api/v1/tasks/{task_id}	Returns task status, request id, result payload, and error details for the authenticated owner.
POST	/api/v1beta/models/{model}:generateContent	Accepts Gemini contents and generationConfig, then normalizes through the platform pipeline.

Async task lifecycle

Image, video, and audio requests return a task id first. A scheduler calls the internal media job, which updates the task to completed or failed, refunds credits on terminal failure, and delivers optional callbacks.

Task creation response

{
  "task_id": "task_123",
  "status": "pending",
  "poll_url": "/api/v1/tasks/task_123",
  "request_id": "req_abc",
  "callback": {
    "status": "pending"
  }
}