Per-request billing: request IDs and billed amounts

Where the request ID comes from

Every successful response from the LLM endpoints (/v1/chat/completions, /v1/messages, the native Gemini /v1beta, /v1/responses and /v1/completions) carries the x-apimodels-request-id header; its value is the task_id of that request. Non-streaming responses also carry x-apimodels-cost: the amount actually deducted, in USD, after every discount on your account, written only once the deduction has completed. Streaming responses carry the ID only, because the amount is known when the last chunk settles; look the record up with the ID.

HTTP/2 200
content-type: application/json
x-apimodels-request-id: cmumilhfd0013mg012q3qobr9
x-apimodels-cost: 0.0001
access-control-expose-headers: x-apimodels-request-id, x-apimodels-cost

usage.cost in the response body

OpenAI and Anthropic SDKs usually hide response headers, so the same amount is also written into the response body as usage.cost. In a non-streaming response usage.cost.charged is the amount deducted, the same number as x-apimodels-cost.

{
  "id": "chatcmpl-…",
  "choices": [ … ],
  "usage": {
    "prompt_tokens": 165,
    "completion_tokens": 6,
    "cost": { "currency": "USD", "amount": 0.0001, "discount": 1, "charged": 0.0001 }
  }
}

Streaming responses put usage.cost in the final chunk that carries usage: the usage chunk you get with stream_options.include_usage in the OpenAI format, message_delta in the Anthropic format (/v1/messages), and response.usage inside response.completed on /v1/responses. That chunk goes out before the deduction is written, so charged is the amount due under the same formula; only a request whose balance ran short ends up deducted for less, and the record lookup is authoritative. message_start carries input usage only and has no cost.

# OpenAI 格式(stream_options.include_usage = true):最后的用量帧
data: {"object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":165,"completion_tokens":6,"cost":{"currency":"USD","amount":0.0001,"discount":1,"charged":0.0001}}}

data: [DONE]

# Anthropic 格式(/v1/messages):message_delta
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"input_tokens":165,"output_tokens":6,"cost":{"currency":"USD","amount":0.0001,"discount":1,"charged":0.0001}}}

usage.cost is returned by /v1/chat/completions, /v1/messages, /v1/responses and /v1/completions; native Gemini /v1beta responses do not include it, so use the record lookup there.

One exception: when a non-streaming LLM request runs past about 95 seconds, the gateway sends the response headers early to keep the connection alive, so the two headers cannot carry values; the same two values are then added to the response body under an apimodels field. The OpenAI and Anthropic SDKs ignore the unknown field.

{
  "id": "chatcmpl-…",
  "choices": [ … ],
  "usage": { … },
  "apimodels": { "request_id": "cmumilhfd0013mg012q3qobr9", "cost": 0.0001 }
}

For image, video and audio tasks the ID is the data.taskId returned at creation. The creation response also carries reservedCredits: the amount put on hold from your balance when the task was accepted, which is the most this task can cost. On completion it settles at the actual amount and the rest is released; a failed task releases all of it.

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "cmum4dq3z00dwlm01wugboo5z",
    "state": "pending",
    "model": "seedance-2.0",
    "reservedCredits": 0.46,
    "currency": "USD"
  }
}

Once the task finishes, both the GET ?task_id= result and the callback (callback_url) carry credits (the final amount deducted) and currency in data, equal to what the record lookup returns.

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "cmum4dq3z00dwlm01wugboo5z",
    "state": "completed",
    "credits": 0.338,
    "currency": "USD",
    "resultUrls": ["https://r2.apimodels.app/videos/cmum4dq3z00dwlm01wugboo5z.mp4"]
  }
}

When calling from a browser, both headers are exposed through Access-Control-Expose-Headers, so response.headers.get() can read them.

Look up a record

GET /api/v1/records/{task_id}
Authorization: Bearer <API_KEY>

curl https://api.apimodels.app/v1/records/cmumilhfd0013mg012q3qobr9 \
  -H "Authorization: Bearer $API_KEY"

import requests, os

# 1) make the call and keep the request id from the response headers
r = requests.post(
    "https://api.apimodels.app/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"model": "claude-haiku-5-5", "messages": [{"role": "user", "content": "Hi"}]},
)
request_id = r.headers["x-apimodels-request-id"]
print("charged now:", r.headers.get("x-apimodels-cost"))   # non-streaming only

# 2) any time later: the authoritative billed amount for that one request
rec = requests.get(
    f"https://api.apimodels.app/v1/records/{request_id}",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
).json()["data"]
print(rec["settled"], rec["credits"], rec["currency"])

const headers = { Authorization: "Bearer " + process.env.API_KEY };

// 1) make the call and keep the request id from the response headers
const r = await fetch("https://api.apimodels.app/v1/chat/completions", {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "claude-haiku-5-5", messages: [{ role: "user", content: "Hi" }] }),
});
const requestId = r.headers.get("x-apimodels-request-id");
console.log("charged now:", r.headers.get("x-apimodels-cost")); // non-streaming only

// 2) any time later: the authoritative billed amount for that one request
const rec = await fetch("https://api.apimodels.app/v1/records/" + requestId, { headers });
const { data } = await rec.json();
console.log(data.settled, data.credits, data.currency);

Resposta

{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "cmumilhfd0013mg012q3qobr9",
    "model": "claude-haiku-5-5",
    "type": "LANGUAGE_MODEL",
    "state": "completed",
    "settled": true,
    "credits": 0.0001,
    "currency": "USD",
    "usage": {
      "input_tokens": 165,
      "output_tokens": 6,
      "cached_input_tokens": 149,
      "cache_creation_tokens": 0
    },
    "created_at": 1790676571513,
    "completed_at": 1790676572799
  }
}

What the amount means

• credits is what finally left the balance, not list price times usage: account discounts and negotiated per-model prices are already applied.
• Failed requests are always 0. Upstream errors, requests rejected by our validation, and timeouts are not charged.
• Streaming LLM calls settle on the last chunk; video models billed by output length settle once the clip exists. Until then settled is false.
• x-apimodels-cost, usage.cost.charged in a non-streaming response and the record’s credits are the same number; the record is the source of truth, the header and body just save you a lookup.
• usage.cost.charged is roughly amount × discount. For LLM calls both amount and charged are rounded to 4 decimal places with a $0.0001 minimum per request; on accounts with negotiated per-model prices, charged is the number to use.
• reservedCredits is a ceiling, not the bill: while held, that part of your balance cannot be used by other requests, and whatever is not charged returns to your available balance at settlement.
• Amounts are kept to 6 decimal places (one millionth of a dollar).

Erros

• 401 — Chave API ausente ou inválida
• 404 — Record not found. A request ID that belongs to another account also returns 404; its existence is never confirmed
• 500 — Erro interno do servidor