Gemini-compatible API

Updated

REST prefix https://modelportal.ai/v1beta, authenticated with x-goog-api-key: YOUR_API_KEY, the query parameter key=YOUR_API_KEY, or Authorization: Bearer YOUR_API_KEY; if you send more than one, they must match. Requests and responses follow the Gemini API. {model} in the path is the model ID, with its slash written as is or as %2F.

POST /v1beta/models/{model}:generateContent

Field Type Required Notes
contents array Yes Conversation contents; parts support text, inlineData, fileData, functionCall and functionResponse
systemInstruction object No System prompt
generationConfig object No temperature, topP, topK, maxOutputTokens, candidateCount, responseMimeType, responseSchema, thinkingConfig and so on; without maxOutputTokens the platform fills one from the model limit and your available balance
tools, toolConfig — No Function calling 
{
  "candidates": [{"content": {"role": "model", "parts": [{"text": "Hello!"}]}, "finishReason": "STOP"}],
  "usageMetadata": {"promptTokenCount": 9, "candidatesTokenCount": 4, "totalTokenCount": 13, "cost": 0.000013},
  "provider": "PROVIDER_ID",
  "attempts": [{"provider": "PROVIDER_ID", "endpoint": "ENDPOINT_ID", "status": 200, "cost": 0.000013}],
  "modelVersion": "MODEL_ID"
}

usageMetadata is the billed usage: promptTokenCount includes cache reads and writes, candidatesTokenCount excludes reasoning, and thoughtsTokenCount and cachedContentTokenCount are listed separately. usageMetadata.cost is the charge for this call (USD); provider and attempts name the provider that served it and each attempt. When streaming, these three are in the last chunk with usageMetadata. Response headers are in the API overview.

POST /v1beta/models/{model}:streamGenerateContent

Same body as generateContent. With ?alt=sse it streams SSE; without it you get a JSON array.

POST /v1beta/models/{model}:countTokens

Counts input tokens for free. The body may be contents or a generateContentRequest.

POST /v1beta/models/{model}:embedContent and :batchEmbedContents

Creates embeddings; the model needs the embedding capability. In batchEmbedContents, each item's model must be empty or match the model in the path.

GET /v1beta/models

Lists the models this key may call, with each model's supported methods and token limits.

Errors

Error bodies are {"error": {"code", "message", "status"}}, where code is the HTTP status and status depends only on it:

HTTP status
400, 422 INVALID_ARGUMENT
401 UNAUTHENTICATED
402, 429 RESOURCE_EXHAUSTED
403 PERMISSION_DENIED
404, 410 NOT_FOUND
502, 503 UNAVAILABLE

On 422, error.excluded lists the exclusion reasons. The platform codes behind each status are in Common errors.