Special model APIs

After you hold an API key, besides chat you can call the six APIs below. Every successful call is written to the personal call log and the admin request list, and billed at the unit price of the upstream that actually handled the request.

When a provider has not declared the matching API, that purpose cannot be selected. The catalog states the reason, for example "this provider does not offer a rerank API".

Judge

Answer yes/no, choice, or scoring questions about a piece of content. It can be selected as the intent-recognition model in global settings, or distributed so callers use the judge API.

POST /v1/decisions

{
  "model": "your-gateway-model",
  "input": "This order was charged twice.",
  "questions": [
    {
      "name": "is_complaint",
      "instructions": "Is this a complaint?",
      "type": "predicate"
    },
    {
      "name": "department",
      "instructions": "Which department should handle it?",
      "type": "choice",
      "choices": [
        { "value": "billing", "description": "Payment, invoices, and refunds." },
        { "value": "other", "description": "None of the above." }
      ]
    }
  ]
}

The same purpose also has POST /v1/systemone. The body puts the content being judged in state, and questions is an object indexed by question name. The gateway normalizes it into the same kind of judge request, then encodes it for the chosen upstream.

Billing is by token. Judge bills both input and output; the output price may be 0. Embedding bills input only.

Limits:

• At most 256 questions per request. When that exceeds the chosen upstream's per-batch cap, the gateway splits by the cap, sends concurrently, and merges answers by question name. Each batch is recorded as one usage row.
• A choice question needs at least 2 options. A scoring question needs at least 1 grade. Question names cannot repeat.
• Images may only sit in a data: URL. An upstream that does not accept images returns 400.
• A missing question, an extra question, or an answer not in the options is refused, naming which question.
• Request-body cap 32 MiB.
• Judge scores from different upstreams cannot be compared directly.

Rerank

POST /v1/rerank

{
  "model": "your-gateway-model",
  "query": "refund progress",
  "documents": ["The order has shipped.", "The refund will arrive within three business days."]
}

Billing is by search count. When upstream returns a search count, that value is used. When it does not, it is computed as 1 query plus 1 per 100 documents. The price on the UI is per thousand searches.

Embedding

POST /v1/embeddings

{
  "model": "your-gateway-model",
  "input": "Turn this text into a vector."
}

Billing is by input tokens.

Image

POST /v1/images/generations

{
  "model": "your-gateway-model",
  "prompt": "A product photo on a blue background",
  "n": 1
}

Billing is by the number of images returned. The price is filled in per image.

Speech synthesis

POST /v1/audio/speech

{
  "model": "your-gateway-model",
  "input": "Hello, this is a speech sample.",
  "voice": "alloy"
}

Billing is by character count of the request text, counted as Unicode scalars. The price is filled in per million characters. Request-body cap 32 MiB.

Speech transcription

Upload a file: POST /v1/audio/transcriptions, multipart/form-data, fields model and file.

Billing is by audio duration. On upload the gateway reads only the container header; it does not decode the whole audio. In the catalog the price is per second; on the UI it is filled in per minute. An unrecognized format returns 400 with "unable to recognize the audio format". File request-body cap 25 MiB.

Realtime transcription uses WebSocket. Cost is computed from the accumulated duration of audio frames received in this session.

Video

How video is billed depends on the upstream. Token-billed models use the video-token count the upstream reports; the price is filled in per million video tokens.

Second-billed models are priced by resolution tier; the price is filled in per second. Billed duration is taken, in order, from the duration the upstream reports, the duration in the request, then the model default duration. The tier is taken in the same order, but the two are chosen independently and may come from different sources. The actual duration of the video file is only for checking; it does not decide the amount. The request detail shows both billed duration and actual duration, and lists Billed-duration basis and Billed-tier basis separately.

Realtime speech

Realtime speech is settled once when the session ends. A token-billed upstream prices reported text, audio, and image tokens separately. The cache-hit portion is also priced by modality: text cache hit, audio cache hit, and image cache hit each have a price, all filled in per million tokens. A duration-billed upstream is computed from audio duration; the price is filled in per minute, and audio and image token price items do not appear.

When pricing an OpenAI realtime model, Audio cache-hit price is required. Image input price and Image cache-hit price always appear and may be left empty — a caller may send an image into the session at any time. They are not hidden by the model's capability declaration; otherwise an image session would be unpriced as a whole row, with no price field to fill in on the form. When the session contains an image and no price is configured, that call is recorded as unpriced. Text cache hit on the form corresponds only to text.

The request's cache-hit count (and the cache-hit rate computed from it) for realtime speech counts only text cache, not audio or image cache. When upstream reports only a total cache count with no per-modality split, the gateway does not infer per-modality cache counts. That call is recorded as unmeterable, and the detail states that upstream did not report cache usage by modality.

When a session ends early because of disconnect, hitting the maximum duration, or similar, usage already produced is settled as usual.

Calls whose cost could not be computed

When a call succeeds but the amount cannot be computed, the cost column of the request list shows one of the two results below. Those calls are not included in amounts:

• Unpriced: a price item this call used has no price configured. The request detail states which price items are missing. After configuration, later calls are billed normally. Already-occurred calls are not backfilled.
• Unmeterable: neither upstream nor the request gave a trustworthy usage, or usage is not enough to split by price item (for example realtime speech reported only a total cache count). The request detail states the reason.

The model-service list shows the count of such calls, and you can open the matching request list.

Quotas

A token quota counts only token-billed usage. It does not count models billed per image, per second, or per character. Setting a token quota to 0 rejects every call. To constrain those models, use an amount quota. Amount is counted from the actual cost after the call ends.

Errors

When the model does not support the API being called, the response is 400 with "this model does not support this API". When every chosen upstream fails, the response is 502. Errors all carry a Chinese message and a stable error code. How status is decided, the full reason table, and the error-body shape of the three protocols are in Error reference.