用量与计费查询

The Syon usage and billing APIs let you retrieve token usage and charges for individual model requests, aggregate usage and billing over a time range, and check the current account balance. This document describes the API contract. Actual production responses take precedence.

API overview

Endpoint	Description
`GET /v1/billing/requests/{request_id}`	Retrieve token usage and billing for a single request
`GET /v1/billing/costs`	Retrieve billing totals for the authenticated API key over a time range
`GET /v1/usage`	Retrieve token usage totals for the authenticated API key over a time range
`GET /v1/billing/balance`	Retrieve the current account balance

Getting started

Base URL

Use the API Base URL shown in the Syon console. The examples below refer to it as $TEAMO_BASE_URL: bash

export TEAMO_BASE_URL="https://syon.com"

Authentication

Send your Syon API key in the Authorization header of every request: http

Authorization: Bearer sk-xxx

Keep your API key secure. Do not include it in frontend code, public repositories, or logs. All keys and IDs in the examples are fictional.

Retrieve usage and billing for a single request

Use a request ID to retrieve the token usage and final charge for one model call. http

GET /v1/billing/requests/{request_id}

Path parameters

Parameter	Type	Required	Description
`request_id`	UUID string	Yes	Request ID returned by the model call

Request example

bash

curl "$TEAMO_BASE_URL/v1/billing/requests/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Response example

json

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": 1784081234,
  "model": "gpt-5.4",
  "usage": {
    "input_tokens": 1000,
    "output_tokens": 500,
    "cached_write_tokens": 800,
    "cached_read_tokens": 200,
    "total_tokens": 2500
  },
  "amount": {
    "value": "0.012680",
    "currency": "USD"
  }
}

Token fields

Field	Description
`input_tokens`	Input tokens that did not use the cache
`output_tokens`	Tokens generated by the model
`cached_write_tokens`	Tokens written to the prompt cache
`cached_read_tokens`	Tokens read from the prompt cache
`total_tokens`	Sum of all token categories above

Token categories that do not apply or are not provided by the upstream service return 0.

Retrieve billing for a time range

Retrieve billing totals for the authenticated API key over a time range. The basic response contains aggregate data only, not individual request records. http

GET /v1/billing/costs

Query parameters

Parameter	Type	Required	Description
`start_time`	integer	Yes	Start of the query range, inclusive
`end_time`	integer	Yes	End of the query range, exclusive

The query range must not exceed 90 days. Longer ranges return 400 invalid_request.

Request example

bash

curl "$TEAMO_BASE_URL/v1/billing/costs?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Response example

json

{
  "start_time": 1784044800,
  "end_time": 1784131200,
  "total_amount": {
    "value": "1.280000",
    "currency": "USD"
  },
  "requests": 86
}

Retrieve token usage for a time range

Retrieve aggregate token usage for the authenticated API key over a time range. http

GET /v1/usage

Query parameters

Parameter	Type	Required	Description
`start_time`	integer	Yes	Start of the query range, inclusive
`end_time`	integer	Yes	End of the query range, exclusive

The query range must not exceed 90 days. Longer ranges return 400 invalid_request.

Request example

bash

curl "$TEAMO_BASE_URL/v1/usage?start_time=1784044800&end_time=1784131200" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Response example

json

{
  "start_time": 1784044800,
  "end_time": 1784131200,
  "usage": {
    "input_tokens": 120000,
    "output_tokens": 30000,
    "cached_write_tokens": 10000,
    "cached_read_tokens": 80000,
    "total_tokens": 240000
  },
  "requests": 86
}

Retrieve the account balance

Retrieve the available balance for the account associated with the current API key. http

GET /v1/billing/balance

This endpoint does not accept query parameters. The API key identifies the account.

Request example

bash

curl "$TEAMO_BASE_URL/v1/billing/balance" \
  -H "Authorization: Bearer $TEAMO_API_KEY"

Response example

json

{
  "balance": {
    "value": "85.320000",
    "currency": "USD"
  }
}

Error handling

When an API call fails, the response body contains a stable error code and a message that helps diagnose the problem. json

{
  "error": {
    "code": "invalid_request",
    "message": "end_time must be greater than start_time"
  }
}

Common error codes

HTTP status	`error.type` / `error.code`	Description
`400`	`invalid_request`	Invalid request parameters, such as an invalid time range
`401`	`missing_auth_credential` / `401`	The API key is missing
`401`	`invalid_api_key`	The API key is invalid
`404`	`not_found`	The request record does not exist or is not accessible to the current API key
`429`	`rate_limit_exceeded`	Too many requests; retry later
`500`	`internal_error`	Internal service error

Recommendations

Use the same start_time and end_time when reconciling usage and billing so both queries use the same scope.
Prices may change. Use the amount returned with historical billing records instead of recalculating past charges from the current price list.
Configure reasonable timeouts and retries. Use exponential backoff for 429 and 5xx responses.

开始

图像生成

接入客户端

用量与计费查询

API overview

Getting started

Base URL

Authentication

Retrieve usage and billing for a single request

Path parameters

Request example

Response example

Token fields

Retrieve billing for a time range

Query parameters

Request example

Response example

Retrieve token usage for a time range

Query parameters

Request example

Response example

Retrieve the account balance

Request example

Response example

Error handling

Common error codes

Recommendations

​API overview

​Getting started

​Base URL

​Authentication

​Retrieve usage and billing for a single request

​Path parameters

​Request example

​Response example

​Token fields

​Retrieve billing for a time range

​Query parameters

​Request example

​Response example

​Retrieve token usage for a time range

​Query parameters

​Request example

​Response example

​Retrieve the account balance

​Request example

​Response example

​Error handling

​Common error codes

​Recommendations

API overview

Getting started

Base URL

Authentication

Retrieve usage and billing for a single request

Path parameters

Request example

Response example

Token fields

Retrieve billing for a time range

Query parameters

Request example

Response example

Retrieve token usage for a time range

Query parameters

Request example

Response example

Retrieve the account balance

Request example

Response example

Error handling

Common error codes

Recommendations