V1 API Common Conventions

This document describes authentication, billing, shared objects, and error response formats for the V1 Open API (/v1/*).

Scope: Public /v1 Relay endpoints — 12 in total.

Common conventions

Base URL

https://www.guid.ai

Endpoints are mounted at the domain root, e.g. POST https://www.guid.ai/v1/chat/completions.

Authentication

All public /v1 endpoints use Bearer Token:

Authorization: Bearer sk-xxxxxxxxxxxxxxxx

Exception: GET /v1/videos/{task_id}/content supports both an admin console Session and a Bearer Token.

Content-Type

Billing

• The gateway selects an upstream channel automatically based on model in the request body (or path parameter)
• Supports token-based, per-request, per-second, and other billing strategies
• Different API Keys may see different model lists

Shared response objects

usage (token billing)

Common in text endpoint responses (Chat / Completions / Responses):

usage (per-request billing, images)

Error responses

Standard errors (text / images / audio / video content)

HTTP status codes: 400, 401, 403, 404, 429, 500, etc.

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error",
    "code": "invalid_request",
    "param": "model"
  }
}

Task errors (video task create / query failure)

HTTP status codes: 400, 429, etc.

{
  "code": "invalid_request",
  "message": "model is required"
}

On HTTP 429, message is: 当前分组上游负载已饱和，请稍后再试 (upstream load for the current group is saturated; try again later).

Gateway extended errors (model list, voice list, etc.)

HTTP status codes: 200 (business failure) or 400.

{
  "success": false,
  "message": "get user group failed"
}

Token balance & usage details

In addition to Relay endpoints, V1 provides two query endpoints. Authentication matches other /v1 APIs: Authorization: Bearer sk-xxxxxxxx. Each request can only query data for the current Bearer token.

Authentication: Use Bearer Token. The token is resolved by the auth middleware — do not pass a key query parameter.

GET /v1/token/balance

Query the balance of the current Bearer token, returning the remaining and used quota in ⚡.

Auth: Authorization: Bearer sk-xxxxxxxx

Request parameters

No query parameters.

Request example (curl)

curl https://www.guid.ai/v1/token/balance \
  -H "Authorization: Bearer sk-xxxxx"

Response body

HTTP 200

{
  "success": true,
  "message": "",
  "data": {
    "id": 1,
    "name": "API Token",
    "remain_quota_usd": 0.2,
    "used_quota_usd": 0.1,
    "unlimited_quota": false
  }
}

Response fields

GET /v1/token/consume

Paginated query of consume records for the current Bearer API Key (type = 2 only). Filtered by token_id — does not return the owning user's top-up/income wallet logs, and does not aggregate consume logs from the user's other keys.

Auth: Authorization: Bearer sk-xxxxxxxx

Request parameters

Request example (curl)

curl "https://www.guid.ai/v1/token/consume?page=1&page_size=10&time_range=today" \
  -H "Authorization: Bearer sk-xxxxx"

Response body

HTTP 200

{
  "success": true,
  "message": "",
  "code": 0,
  "data": {
    "page": 1,
    "page_size": 10,
    "total": 100,
    "items": [
      {
        "id": 1,
        "created_at": 1700000000,
        "type": 2,
        "type_name": "消费",
        "content": "模型推理",
        "token_name": "default",
        "model_name": "gpt-3.5-turbo",
        "app_name": "",
        "usage_name": "gpt-3.5-turbo",
        "quota_usd": 0.002,
        "quota_type": 2
      }
    ]
  }
}

Response fields

Related docs

• Quick Start
• Choosing an Integration
• Glossary
• Models · Text · Images · Videos · Audio