{
  "components": {
    "responses": {
      "Error": {
        "content": {
          "application/json": {
            "example": {
              "error": {
                "code": "AUTH_FAILED",
                "message": "missing credentials: send Authorization: Bearer ak-...",
                "request_id": "req_01M2569REZ8VNEWYQJ7309F5SD"
              }
            },
            "schema": {
              "$ref": "#/components/schemas/ErrorBody"
            }
          }
        },
        "description": "frozen error envelope"
      }
    },
    "schemas": {
      "AnthropicBillingEvent": {
        "additionalProperties": false,
        "description": "流式结尾的平台事件：`event: asterapi_billing`，data 即本对象。",
        "properties": {
          "billable_units": {
            "$ref": "#/components/schemas/BillableUnits"
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "request_id",
          "billable_units"
        ],
        "type": "object",
        "x-forbidden-keys": [
          "cost",
          "cost_details",
          "is_byok",
          "provider",
          "sales_amount"
        ]
      },
      "AnthropicMessage": {
        "additionalProperties": true,
        "description": "上游 Anthropic 形状原样透传，外加平台字段。usage 的缓存两键恒为 0。",
        "properties": {
          "billable_units": {
            "$ref": "#/components/schemas/BillableUnits"
          },
          "content": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "id": {
            "description": "与 request_id 相同",
            "type": "string"
          },
          "model": {
            "description": "请求时的别名",
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "role": {
            "const": "assistant",
            "type": "string"
          },
          "stop_reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "stop_sequence": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "const": "message",
            "type": "string"
          },
          "usage": {
            "additionalProperties": true,
            "properties": {
              "cache_creation_input_tokens": {
                "const": 0,
                "type": "integer"
              },
              "cache_read_input_tokens": {
                "const": 0,
                "type": "integer"
              },
              "input_tokens": {
                "type": "integer"
              },
              "output_tokens": {
                "type": "integer"
              }
            },
            "required": [
              "input_tokens",
              "output_tokens"
            ],
            "type": "object"
          }
        },
        "required": [
          "id",
          "type",
          "role",
          "model",
          "content",
          "usage",
          "request_id",
          "billable_units"
        ],
        "type": "object",
        "x-forbidden-keys": [
          "cost",
          "cost_details",
          "is_byok",
          "provider",
          "sales_amount"
        ]
      },
      "BillableUnits": {
        "additionalProperties": false,
        "description": "平台计费口径：这一笔按多少 token 计的费。input_tokens 是全部输入 token（新鲜的、读缓存的、写缓存的加在一起）， 客户面只有一个输入价。usage_source 说明数字从哪来：upstream = 上游报的；provider_bill = 供应商账单； local-estimated = 上游没报、本地估算（可辨认，方便对账）。\n",
        "properties": {
          "input_tokens": {
            "type": "integer"
          },
          "output_tokens": {
            "type": "integer"
          },
          "usage_source": {
            "enum": [
              "upstream",
              "provider_bill",
              "local-estimated"
            ],
            "type": "string"
          }
        },
        "required": [
          "input_tokens",
          "output_tokens",
          "usage_source"
        ],
        "type": "object"
      },
      "ChatCompletion": {
        "additionalProperties": true,
        "description": "上游 OpenAI 形状原样透传（choices / usage 里可能带上游特有的附加键，例如 reasoning_content、 prompt_tokens_details），外加平台字段。请以 billable_units 为计费依据，usage 只是上游自报。\n",
        "properties": {
          "billable_units": {
            "$ref": "#/components/schemas/BillableUnits"
          },
          "choices": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "created": {
            "type": "integer"
          },
          "id": {
            "description": "与 request_id 相同",
            "type": "string"
          },
          "model": {
            "description": "请求时的别名",
            "type": "string"
          },
          "object": {
            "const": "chat.completion",
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "usage": {
            "additionalProperties": true,
            "description": "上游自报用量，形状随上游；标准键为 prompt_tokens / completion_tokens / total_tokens",
            "properties": {
              "completion_tokens": {
                "type": "integer"
              },
              "prompt_tokens": {
                "type": "integer"
              },
              "total_tokens": {
                "type": "integer"
              }
            },
            "type": "object"
          }
        },
        "required": [
          "id",
          "object",
          "created",
          "model",
          "choices",
          "request_id",
          "billable_units"
        ],
        "type": "object",
        "x-forbidden-keys": [
          "cost",
          "cost_details",
          "is_byok",
          "provider",
          "native_finish_reason",
          "sales_amount"
        ]
      },
      "ErrorBody": {
        "additionalProperties": false,
        "properties": {
          "error": {
            "additionalProperties": false,
            "properties": {
              "code": {
                "description": "14 个冻结错误码及 HTTP 状态：INVALID_REQUEST 400 · AUTH_FAILED 401 · INSUFFICIENT_BALANCE 402 · PERMISSION_DENIED 403 · MODEL_NOT_FOUND 404 · NOT_FOUND 404 · REQUEST_IN_PROGRESS 409 · CONTENT_BLOCKED 422 · BUDGET_EXCEEDED 429 · RATE_LIMITED 429 · MODEL_RATE_LIMITED 429 · UPSTREAM_ERROR 502 · UPSTREAM_TIMEOUT 504 · INTERNAL_ERROR 500\n",
                "enum": [
                  "INVALID_REQUEST",
                  "AUTH_FAILED",
                  "PERMISSION_DENIED",
                  "MODEL_NOT_FOUND",
                  "NOT_FOUND",
                  "INSUFFICIENT_BALANCE",
                  "BUDGET_EXCEEDED",
                  "RATE_LIMITED",
                  "MODEL_RATE_LIMITED",
                  "REQUEST_IN_PROGRESS",
                  "CONTENT_BLOCKED",
                  "UPSTREAM_TIMEOUT",
                  "UPSTREAM_ERROR",
                  "INTERNAL_ERROR"
                ],
                "type": "string"
              },
              "message": {
                "description": "面向人的说明，不含上游原文、凭据或供应商身份",
                "type": "string"
              },
              "request_id": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ],
            "type": "object"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "ImageTask": {
        "additionalProperties": false,
        "properties": {
          "billing": {
            "additionalProperties": false,
            "properties": {
              "currency": {
                "const": "CNY",
                "type": "string"
              },
              "reserved_micro_cny": {
                "description": "仅预占期间返回；这是本次扣款上限而非最终价格",
                "minimum": 0,
                "type": "integer"
              },
              "sales_micro_cny": {
                "description": "已扣款为实际用量结算金额；预占和释放时为零",
                "minimum": 0,
                "type": "integer"
              },
              "status": {
                "enum": [
                  "held",
                  "charged",
                  "released",
                  "waived"
                ],
                "type": "string"
              }
            },
            "required": [
              "status",
              "sales_micro_cny",
              "currency"
            ],
            "type": "object"
          },
          "error_code": {
            "type": "string"
          },
          "hold_expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "images": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "expires_at": {
                  "type": "integer"
                },
                "url": {
                  "format": "uri",
                  "type": "string"
                }
              },
              "required": [
                "url",
                "expires_at"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "request_id": {
            "type": "string"
          },
          "retry_after": {
            "minimum": 0,
            "type": "integer"
          },
          "status": {
            "enum": [
              "accepted",
              "dispatching",
              "running",
              "unknown",
              "succeeded",
              "failed"
            ],
            "type": "string"
          },
          "task_id": {
            "type": "string"
          }
        },
        "required": [
          "task_id",
          "status",
          "billing",
          "hold_expires_at",
          "retry_after"
        ],
        "type": "object"
      },
      "ImageTaskError": {
        "properties": {
          "error": {
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "request_id": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message",
              "request_id"
            ],
            "type": "object"
          }
        },
        "required": [
          "error"
        ],
        "type": "object"
      },
      "ImageTaskInput": {
        "additionalProperties": false,
        "properties": {
          "client_request_id": {
            "maxLength": 128,
            "minLength": 1,
            "type": "string"
          },
          "image_urls": {
            "items": {
              "type": "string"
            },
            "maxItems": 4,
            "type": "array"
          },
          "model": {
            "enum": [
              "gpt-image-2-official"
            ],
            "type": "string"
          },
          "n": {
            "const": 1,
            "type": "integer"
          },
          "prompt": {
            "maxLength": 64000,
            "minLength": 1,
            "type": "string"
          },
          "quality": {
            "enum": [
              "low",
              "medium",
              "high"
            ],
            "type": "string"
          },
          "resolution": {
            "description": "4k 仅支持 16:9、9:16、2:1、1:2、21:9、9:21",
            "enum": [
              "1k",
              "2k",
              "4k"
            ],
            "type": "string"
          },
          "size": {
            "enum": [
              "auto",
              "1:1",
              "3:2",
              "2:3",
              "4:3",
              "3:4",
              "5:4",
              "4:5",
              "16:9",
              "9:16",
              "2:1",
              "1:2",
              "21:9",
              "9:21"
            ],
            "type": "string"
          },
          "submit_not_after": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "client_request_id",
          "submit_not_after",
          "model",
          "prompt",
          "size",
          "resolution",
          "quality",
          "n"
        ],
        "type": "object"
      },
      "ModelList": {
        "additionalProperties": false,
        "properties": {
          "data": {
            "items": {
              "additionalProperties": false,
              "properties": {
                "capabilities": {
                  "description": "该别名支持的能力，如 `chat` / `stream` / `tools` / `gemini_native` / `video_understanding` / `image_generation`。只在 `?include=all` 时返回。\n",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "created": {
                  "description": "Unix 秒",
                  "type": "integer"
                },
                "id": {
                  "description": "目录别名，填进请求的 model",
                  "type": "string"
                },
                "object": {
                  "const": "model",
                  "type": "string"
                },
                "owned_by": {
                  "const": "apipace",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "object",
                "created",
                "owned_by"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "object": {
            "const": "list",
            "type": "string"
          }
        },
        "required": [
          "object",
          "data"
        ],
        "type": "object"
      },
      "NativeJob": {
        "additionalProperties": false,
        "properties": {
          "attempt": {
            "minimum": 0,
            "type": "integer"
          },
          "error_code": {
            "type": "string"
          },
          "job_id": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "result": {
            "additionalProperties": true,
            "type": "object"
          },
          "retry_after": {
            "minimum": 0,
            "type": "integer"
          },
          "state": {
            "enum": [
              "queued",
              "running",
              "succeeded",
              "failed",
              "unknown"
            ],
            "type": "string"
          }
        },
        "required": [
          "job_id",
          "state",
          "attempt",
          "retry_after"
        ],
        "type": "object"
      },
      "OpenAIBillingChunk": {
        "additionalProperties": false,
        "description": "流式最后一个平台帧（在上游 usage 帧之后、`[DONE]` 之前）。choices 恒为空数组。",
        "properties": {
          "billable_units": {
            "$ref": "#/components/schemas/BillableUnits"
          },
          "choices": {
            "items": {
              "type": "object"
            },
            "maxItems": 0,
            "type": "array"
          },
          "created": {
            "type": "integer"
          },
          "id": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "object": {
            "const": "chat.completion.chunk",
            "type": "string"
          }
        },
        "required": [
          "id",
          "object",
          "created",
          "model",
          "choices",
          "billable_units"
        ],
        "type": "object",
        "x-forbidden-keys": [
          "cost",
          "cost_details",
          "is_byok",
          "provider",
          "native_finish_reason",
          "sales_amount"
        ]
      },
      "PricingCatalog": {
        "additionalProperties": false,
        "properties": {
          "book_version": {
            "description": "生效价目簿版本号；没有生效簿时不返回",
            "type": "integer"
          },
          "currency": {
            "const": "CNY",
            "type": "string"
          },
          "effective_at": {
            "description": "该簿的生效时刻",
            "format": "date-time",
            "type": "string"
          },
          "image_models": {
            "description": "按五个 token 桶计价的图片别名，字典序",
            "items": {
              "additionalProperties": false,
              "properties": {
                "capabilities": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "display_name": {
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "tariff": {
                  "additionalProperties": false,
                  "description": "销售侧五桶单价，官方美元牌价，每百万 token 的整数微美元",
                  "properties": {
                    "cached_image_input_micro_usd_per_m": {
                      "minimum": 0,
                      "type": "integer"
                    },
                    "cached_text_input_micro_usd_per_m": {
                      "minimum": 0,
                      "type": "integer"
                    },
                    "image_input_micro_usd_per_m": {
                      "minimum": 0,
                      "type": "integer"
                    },
                    "image_output_micro_usd_per_m": {
                      "minimum": 0,
                      "type": "integer"
                    },
                    "text_input_micro_usd_per_m": {
                      "minimum": 0,
                      "type": "integer"
                    },
                    "version": {
                      "description": "所依据的官方价目版本",
                      "type": "string"
                    }
                  },
                  "required": [
                    "version",
                    "text_input_micro_usd_per_m",
                    "cached_text_input_micro_usd_per_m",
                    "image_input_micro_usd_per_m",
                    "cached_image_input_micro_usd_per_m",
                    "image_output_micro_usd_per_m"
                  ],
                  "type": "object"
                }
              },
              "required": [
                "id",
                "display_name",
                "capabilities"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "models": {
            "description": "按 token 计价的别名，字典序",
            "items": {
              "additionalProperties": false,
              "properties": {
                "capabilities": {
                  "description": "chat / stream / tools / gemini_native / video_understanding 等",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "display_name": {
                  "type": "string"
                },
                "id": {
                  "description": "目录别名，填进请求的 model",
                  "type": "string"
                },
                "input_per_m": {
                  "description": "每百万输入 token 的售价（微元）；读缓存、写缓存同价",
                  "minimum": 0,
                  "type": "integer"
                },
                "output_per_m": {
                  "description": "每百万输出 token 的售价（微元）",
                  "minimum": 0,
                  "type": "integer"
                }
              },
              "required": [
                "id",
                "display_name",
                "capabilities",
                "input_per_m",
                "output_per_m"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "unit": {
            "const": "micro_yuan_per_million_tokens",
            "type": "string"
          }
        },
        "required": [
          "currency",
          "unit",
          "models",
          "image_models"
        ],
        "type": "object",
        "x-forbidden-keys": [
          "input_markup_bp",
          "markup",
          "cached_in_per_m",
          "per_call",
          "cost",
          "cost_amount",
          "provider",
          "provider_id",
          "endpoint_id",
          "upstream_model",
          "route_id",
          "margin",
          "discount_bp"
        ]
      },
      "RequestDetail": {
        "additionalProperties": false,
        "properties": {
          "adjustments": {
            "description": "事后对这笔请求的钱包修正，永远是数组（没有修正就是空数组）",
            "items": {
              "additionalProperties": false,
              "properties": {
                "amount": {
                  "description": "微元；正数是退回给你，负数是补扣",
                  "type": "integer"
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "kind": {
                  "enum": [
                    "debit",
                    "refund",
                    "credit"
                  ],
                  "type": "string"
                },
                "op_id": {
                  "type": "string"
                }
              },
              "required": [
                "op_id",
                "amount",
                "kind",
                "created_at"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "billable_units": {
            "additionalProperties": false,
            "properties": {
              "input_tokens": {
                "type": "integer"
              },
              "output_tokens": {
                "type": "integer"
              },
              "request_count": {
                "type": "integer"
              },
              "usage_source": {
                "enum": [
                  "upstream",
                  "provider_bill",
                  "local-estimated"
                ],
                "type": "string"
              }
            },
            "required": [
              "input_tokens",
              "output_tokens",
              "request_count",
              "usage_source"
            ],
            "type": "object"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "const": "CNY",
            "type": "string"
          },
          "error_code": {
            "description": "失败时的公开错误码",
            "type": "string"
          },
          "latency_ms": {
            "additionalProperties": false,
            "properties": {
              "platform_overhead": {
                "description": "total − upstream_total",
                "type": "integer"
              },
              "total": {
                "type": "integer"
              },
              "upstream_first_byte": {
                "type": "integer"
              },
              "upstream_total": {
                "type": "integer"
              }
            },
            "required": [
              "total",
              "upstream_first_byte",
              "upstream_total",
              "platform_overhead"
            ],
            "type": "object"
          },
          "model": {
            "description": "请求时的别名",
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "route_id": {
            "description": "不透明路由追踪号，与响应头 X-Route-Id 相同",
            "type": "string"
          },
          "sales_amount": {
            "description": "这笔请求当时的扣费，微元，永不改写",
            "type": "integer"
          },
          "status": {
            "description": "请求生命周期状态，如 FINALIZED / COMPLETED / FAILED / REJECTED",
            "type": "string"
          },
          "stream": {
            "type": "boolean"
          },
          "usage": {
            "additionalProperties": false,
            "properties": {
              "input_tokens": {
                "description": "全部输入 token（新鲜 + 读缓存 + 写缓存）",
                "type": "integer"
              },
              "output_tokens": {
                "type": "integer"
              },
              "total_tokens": {
                "type": "integer"
              }
            },
            "required": [
              "input_tokens",
              "output_tokens",
              "total_tokens"
            ],
            "type": "object"
          }
        },
        "required": [
          "request_id",
          "status",
          "model",
          "stream",
          "usage",
          "billable_units",
          "sales_amount",
          "currency",
          "latency_ms",
          "created_at",
          "adjustments"
        ],
        "type": "object",
        "x-forbidden-keys": [
          "cost",
          "cost_amount",
          "provider_id",
          "endpoint_id",
          "provider",
          "margin",
          "candidates",
          "reason"
        ]
      },
      "StatusModel": {
        "additionalProperties": false,
        "properties": {
          "id": {
            "description": "客户可见的模型别名",
            "type": "string"
          },
          "p50_latency_ms": {
            "description": "端到端总耗时中位数",
            "minimum": 0,
            "type": "integer"
          },
          "requests": {
            "description": "窗口内该别名的全部请求数",
            "minimum": 0,
            "type": "integer"
          },
          "upstream_error_rate_bp": {
            "description": "平台侧失败占比，万分之一为单位",
            "maximum": 10000,
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "id",
          "requests",
          "upstream_error_rate_bp",
          "p50_latency_ms"
        ],
        "type": "object"
      },
      "StatusReport": {
        "additionalProperties": false,
        "properties": {
          "models": {
            "description": "只包含 capabilities 含 chat 的别名，按别名排序",
            "items": {
              "$ref": "#/components/schemas/StatusModel"
            },
            "type": "array"
          },
          "overall": {
            "additionalProperties": false,
            "properties": {
              "requests": {
                "minimum": 0,
                "type": "integer"
              },
              "upstream_error_rate_bp": {
                "maximum": 10000,
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "requests",
              "upstream_error_rate_bp"
            ],
            "type": "object"
          },
          "updated_at": {
            "description": "快照生成时刻（UTC），缓存期内不变",
            "format": "date-time",
            "type": "string"
          },
          "window_minutes": {
            "const": 15,
            "type": "integer"
          }
        },
        "required": [
          "window_minutes",
          "updated_at",
          "models",
          "overall"
        ],
        "type": "object",
        "x-forbidden-keys": [
          "provider",
          "provider_id",
          "endpoint",
          "endpoint_id",
          "route",
          "route_id",
          "cost",
          "cost_amount",
          "sales_amount",
          "upstream",
          "tenant_id"
        ]
      }
    },
    "securitySchemes": {
      "apiKey": {
        "description": "x-api-key: ak-…（Anthropic SDK 的默认方式）。两种鉴权任选其一，效力相同。",
        "in": "header",
        "name": "x-api-key",
        "type": "apiKey"
      },
      "bearer": {
        "description": "Authorization: Bearer ak-…（OpenAI SDK / Claude Code 的默认方式）",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "APIPace 是一个多协议的 LLM API 中转站：一把 key，同时讲 OpenAI 和 Anthropic 两种协议，另有 Gemini 原生接口与异步图片任务；人民币微元整数结算，每一笔都能按请求号查回扣费。\n\nBase URL `https://api.apipace.com`。鉴权用 `Authorization: Bearer ak-…` 或 `x-api-key: ak-…`，两者效力相同。`model` 填**别名**，可用别名以 `GET /v1/models` 为准。\n\n**这里是接口参考。** 快速开始、各客户端接入指南、图片生成、Gemini 原生、计费与账单、常见问题在 [文档站](/docs)。\n\n# 计费口径\n\n按 token 计费：每个别名一个输入价、一个输出价。价目表在 [/pricing](https://api.apipace.com/pricing)，机器可读的那份是免鉴权的 `GET /v1/pricing`（整数微元 / 百万 token，缓存 60 秒）。\n\n```\n扣费 = billable_units.input_tokens × 输入单价 + billable_units.output_tokens × 输出单价\n```\n\n整数微元结算（1 元 = 1,000,000 微元）。每笔请求只有两个计费数，都在响应体的 `billable_units` 里：`input_tokens` 是全部输入 token（新鲜的、读缓存的、写缓存的加在一起），`output_tokens` 是输出 token（含推理型模型的思考 token）。\n\n**对话类别名冷热同价**：缓存不单独计价，`usage` 里的缓存字段恒为 0。图片任务是唯一例外，它按五个桶分别计价。\n\n`billable_units.usage_source` 说明数字从哪来：`upstream`（模型服务方报的，绝大多数）、`provider_bill`（服务方账单）、`local-estimated`（没报、本地估算，可辨认）。\n\n**响应体里有 token，没有钱。** 这一笔扣了多少，拿 `request_id` 查 `GET /v1/requests/{id}`，返回的 `sales_amount` 是微元，永不改写；事后冲正以 `adjustments[]` 追加。账户级对账用 `GET /v1/user/statement`，恒等式 `balance + net_spent = funding + adjustments`。\n\n流式请求的计费数在流的最后一帧：Anthropic 协议在 `message_stop` 之后追加 `event: asterapi_billing`；OpenAI 协议在 `[DONE]` 之前追加一个 `choices` 为空、带 `billable_units` 的 chunk。标准 SDK 会忽略它们。\n\n请求开始时按输入估算与 `max_tokens` 预占余额（`held`），结束后按实际用量结算并释放。可用余额 = 余额 − 预占 + 授信；预占不够返回 `INSUFFICIENT_BALANCE`（402）。返空、失败、被拒绝的请求不计费。\n\n# 限制与约定\n\n| 项 | 约定 |\n|---|---|\n| 幂等 | 带 `Idempotency-Key` 的请求，7 天内同键重放返回首发结果、不重复扣费；同键进行中返回 `REQUEST_IN_PROGRESS`（409）。图片任务与 `/v1beta` 必须带 |\n| 关联编号 | 带 `X-Request-ID`（≤ 64 字符）可用 `GET /v1/requests/by-client/{id}` 找回这一笔；它不产生幂等 |\n| 频率 | 每把 key 一秒固定窗口，平台默认 30 次/秒，可在控制台按 key 调严。每个受限响应都带 `X-RateLimit-Limit` / `X-RateLimit-Remaining`；被拒时 429 `RATE_LIMITED` 再加 `Retry-After: 1` |\n| 超时 | 单次请求总预算 300 秒，首 token 60 秒；超过返回 `UPSTREAM_TIMEOUT`（504） |\n| 断开 | 客户端中途断开会取消调用，已产生的用量照常结算 |\n| 白名单 | key 可限定可用别名与来源 IP，越界返回 `PERMISSION_DENIED`（403）；白名单外的别名在 `/v1/models` 里也看不到 |\n| 追踪 | 每个响应带 `X-Request-Id`（同响应体 `request_id`）与 `X-Route-Id`；报问题请带这两个值 |\n| 隐私 | 请求与响应正文默认不留存 |\n\n# 错误码\n\n所有 `/v1` 错误一个形状：\n\n```json\n{\"error\": {\"code\": \"AUTH_FAILED\", \"message\": \"…\", \"request_id\": \"req_…\"}}\n```\n\n`message` 给人看，程序请判 `code`。14 个码是冻结的：\n\n| code | HTTP | 什么情况 |\n|---|---|---|\n| `INVALID_REQUEST` | 400 | 参数或请求体不合法 |\n| `AUTH_FAILED` | 401 | key 缺失、无效、已禁用或过期 |\n| `INSUFFICIENT_BALANCE` | 402 | 可用余额不够预占 |\n| `PERMISSION_DENIED` | 403 | 别名或 IP 不在 key 的白名单里 |\n| `MODEL_NOT_FOUND` | 404 | 别名不存在或对这把 key 不可见 |\n| `NOT_FOUND` | 404 | 资源不存在（如别人的 `request_id`） |\n| `REQUEST_IN_PROGRESS` | 409 | 同一个 `Idempotency-Key` 还在进行中 |\n| `CONTENT_BLOCKED` | 422 | 安全拦截 |\n| `BUDGET_EXCEEDED` | 429 | 账户日 / 月预算用完 |\n| `RATE_LIMITED` | 429 | 这把 key 的每秒请求数超限 |\n| `MODEL_RATE_LIMITED` | 429 | 这个别名当前拿不到配额 |\n| `UPSTREAM_ERROR` | 502 | 模型服务方返回失败（已脱敏） |\n| `UPSTREAM_TIMEOUT` | 504 | 服务方超时 |\n| `INTERNAL_ERROR` | 500 | 平台内部错误 |\n\n`/v1/image-tasks` 与 `/v1beta` 各有一套更细的错误码，见 [图片生成](/docs/images) 与 [Gemini 原生接口](/docs/gemini-native)。\n\n下面是每个接口的完整定义。右侧可以填 key 发一次真实请求试试。\n",
    "title": "APIPace API",
    "version": "1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/status": {
      "get": {
        "description": "最近 15 分钟的聊天模型健康度，30 秒缓存一次。不需要 API key，故障时也能读。 `upstream_error_rate_bp` 只统计平台自己该负责的失败（上游报错、上游超时、 上游限流、内部错误）；请求参数不对、鉴权失败、余额不足这类由调用方造成的 4xx 计入 `requests` 但不计入错误率。`p50_latency_ms` 是端到端总耗时的中位数。 本接口不返回任何上游、路由、渠道或价格信息。\n",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "models": [
                    {
                      "id": "claude-sonnet-4.6",
                      "p50_latency_ms": 1840,
                      "requests": 128,
                      "upstream_error_rate_bp": 0
                    },
                    {
                      "id": "kimi-k3",
                      "p50_latency_ms": 940,
                      "requests": 12,
                      "upstream_error_rate_bp": 833
                    }
                  ],
                  "overall": {
                    "requests": 140,
                    "upstream_error_rate_bp": 71
                  },
                  "updated_at": "2026-09-15T08:20:47Z",
                  "window_minutes": 15
                },
                "schema": {
                  "$ref": "#/components/schemas/StatusReport"
                }
              }
            },
            "description": "15 分钟窗口的聚合快照",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "const": "public, max-age=30",
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "平台健康状态（公开，免鉴权）",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1/chat/completions": {
      "post": {
        "description": "请求体按 OpenAI Chat Completions 传。`model` 填目录里的别名（见 GET /v1/models）。 响应体是上游的 OpenAI 形状原样透传，外加平台字段 `request_id` 与 `billable_units`； `id` 与 `request_id` 相同。上游自报的成本、供应商身份、路由痕迹一律不出现。\n",
        "parameters": [
          {
            "description": "幂等键，7 天内同键重放返回首发结果",
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "maxLength": 128,
              "type": "string"
            }
          },
          {
            "description": "recorded as client_request_id only",
            "in": "header",
            "name": "X-Request-ID",
            "schema": {
              "maxLength": 64,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "max_tokens": 64,
                "messages": [
                  {
                    "content": "say hi",
                    "role": "user"
                  }
                ],
                "model": "kimi-k3"
              },
              "schema": {
                "additionalProperties": true,
                "properties": {
                  "max_tokens": {
                    "type": "integer"
                  },
                  "messages": {
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "model": {
                    "description": "catalog alias",
                    "type": "string"
                  },
                  "stream": {
                    "default": false,
                    "type": "boolean"
                  },
                  "stream_options": {
                    "type": "object"
                  }
                },
                "required": [
                  "model",
                  "messages"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "billable_units": {
                    "input_tokens": 87,
                    "output_tokens": 16,
                    "usage_source": "upstream"
                  },
                  "choices": [
                    {
                      "finish_reason": "stop",
                      "index": 0,
                      "message": {
                        "content": "Hi!",
                        "role": "assistant"
                      }
                    }
                  ],
                  "created": 1789029007,
                  "id": "req_01M25700V1PHY8T8C0E3AXYX4P",
                  "model": "kimi-k3",
                  "object": "chat.completion",
                  "request_id": "req_01M25700V1PHY8T8C0E3AXYX4P",
                  "usage": {
                    "completion_tokens": 16,
                    "prompt_tokens": 87,
                    "prompt_tokens_details": {
                      "cached_tokens": 0
                    },
                    "total_tokens": 103
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ChatCompletion"
                }
              }
            },
            "description": "非流式：JSON（下述 schema）。流式：`text/event-stream`，每帧 `data: {chat.completion.chunk}`， 上游 usage 帧之后是平台计费帧（choices 为空、带 billable_units），最后 `data: [DONE]`。\n",
            "headers": {
              "X-Client-Request-Id": {
                "description": "echoed only when inbound X-Request-ID present",
                "schema": {
                  "type": "string"
                }
              },
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Route-Id": {
                "description": "不透明路由追踪号",
                "schema": {
                  "type": "string"
                }
              }
            },
            "x-sse-final-frame": {
              "$ref": "#/components/schemas/OpenAIBillingChunk"
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "OpenAI 兼容对话补全（流式 / 非流式）",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1/image-tasks": {
      "post": {
        "description": "仅生成一张图片，最多 4 张参考图，每张 base64 解码后不超过 1 MiB，请求体不超过 8 MiB。 Idempotency-Key 必须等于 client_request_id。同一 key 和请求编号重复提交返回原任务，参数改变返回 409。 submit_not_after 必须在未来 3 分钟以内；超过期限不能首次接单，但已经接单的重放仍可查询。 202 表示任务、冻结价格和预占资金已原子持久化。只有成功且未超冻结期限的图片才扣款。 上游回包不确定时不会重复采购，超过 hold_expires_at 释放预占，迟到成功不再追扣。\n",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "maxLength": 128,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImageTaskInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImageTask"
                }
              }
            },
            "description": "已接单或幂等返回原任务"
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImageTaskError"
                }
              }
            },
            "description": "请求未被接受；error.code 提供可判别原因，不包含上游信息"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "创建异步图片任务（持久化接单）",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1/image-tasks/by-client/{clientID}": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "clientID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImageTask"
                }
              }
            },
            "description": "原接单结果；查询不会创建或重新采购图片"
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImageTaskError"
                }
              }
            },
            "description": "当前 key 下没有该任务或鉴权失败"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "按调用方编号恢复丢失的接单响应",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1/image-tasks/{taskID}": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "taskID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImageTask"
                }
              }
            },
            "description": "数据库任务快照，余额耗尽仍可读；结果 URL 有有效期，请及时转存"
          },
          "default": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ImageTaskError"
                }
              }
            },
            "description": "无权限或任务不存在"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "查询当前 key 的图片任务（只读且免费）",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1/messages": {
      "post": {
        "description": "请求体按 Anthropic Messages 传（tools / thinking / images 原样透传），`model` 填目录别名。 响应体是 Anthropic 形状，外加平台字段 `request_id` 与 `billable_units`；`id` 与 `request_id` 相同。 `usage` 里的缓存两键始终为 0：客户面冷热同价，缓存不单独计价。\n",
        "parameters": [
          {
            "description": "幂等键，7 天内同键重放返回首发结果",
            "in": "header",
            "name": "Idempotency-Key",
            "schema": {
              "maxLength": 128,
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "anthropic-version",
            "schema": {
              "default": "2023-06-01",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "max_tokens": 64,
                "messages": [
                  {
                    "content": "say hi",
                    "role": "user"
                  }
                ],
                "model": "claude-sonnet-4.6"
              },
              "schema": {
                "additionalProperties": true,
                "properties": {
                  "max_tokens": {
                    "type": "integer"
                  },
                  "messages": {
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "model": {
                    "description": "catalog alias",
                    "type": "string"
                  },
                  "stream": {
                    "default": false,
                    "type": "boolean"
                  }
                },
                "required": [
                  "model",
                  "messages",
                  "max_tokens"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "billable_units": {
                    "input_tokens": 87,
                    "output_tokens": 16,
                    "usage_source": "upstream"
                  },
                  "content": [
                    {
                      "text": "Hi!",
                      "type": "text"
                    }
                  ],
                  "id": "req_01M25700V1PHY8T8C0E3AXYX4P",
                  "model": "claude-sonnet-4.6",
                  "request_id": "req_01M25700V1PHY8T8C0E3AXYX4P",
                  "role": "assistant",
                  "stop_reason": "end_turn",
                  "stop_sequence": null,
                  "type": "message",
                  "usage": {
                    "cache_creation_input_tokens": 0,
                    "cache_read_input_tokens": 0,
                    "input_tokens": 87,
                    "output_tokens": 16
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/AnthropicMessage"
                }
              }
            },
            "description": "非流式：JSON（下述 schema）。流式：Anthropic 标准事件序列（message_start … message_stop）， 之后追加一个平台事件 `event: asterapi_billing`，data 为 {request_id, billable_units}。\n",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              },
              "X-Route-Id": {
                "description": "不透明路由追踪号",
                "schema": {
                  "type": "string"
                }
              }
            },
            "x-sse-final-frame": {
              "$ref": "#/components/schemas/AnthropicBillingEvent"
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "Anthropic 原生 Messages（流式 / 非流式）",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1/models": {
      "get": {
        "description": "默认只列能直接填进 `/v1/chat/completions`、`/v1/messages` 的对话别名（capabilities 含 `chat`）， 并按 key 的模型白名单过滤。只走 Gemini 原生协议（`/v1beta`）的别名和只走 `/v1/image-tasks` 的图片别名不在默认列表里——把它们填进对话请求只会拿到 400。 `?include=all` 列出全部上架别名，并给每条附上 `capabilities`。 别名可能上下架，以本接口实时返回为准。\n",
        "parameters": [
          {
            "description": "填 `all` 列出全部上架别名并附带 capabilities；其它值按默认（只列对话别名）处理。",
            "in": "query",
            "name": "include",
            "required": false,
            "schema": {
              "enum": [
                "all"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "created": 1788371550,
                      "id": "claude-sonnet-4.6",
                      "object": "model",
                      "owned_by": "apipace"
                    },
                    {
                      "created": 1788297303,
                      "id": "kimi-k3",
                      "object": "model",
                      "owned_by": "apipace"
                    }
                  ],
                  "object": "list"
                },
                "schema": {
                  "$ref": "#/components/schemas/ModelList"
                }
              }
            },
            "description": "OpenAI-compatible model list",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "当前 key 可见的模型别名",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1/pricing": {
      "get": {
        "description": "当前生效价目簿里全部在售别名的售价。金额是整数微元，按每百万 token 计， 除以 1,000,000 得人民币元。免鉴权，可缓存 60 秒。 只出售价：上游身份、采购成本、路由与倍率永不出现在这里。 文字模型的缓存输入与新鲜输入同价，不单独计价，所以只有输入、输出两个价。 图片模型按官方五个 token 桶计价，桶单价以官方美元牌价给出，结算时按平台汇率折成人民币； 提交任务时预占的金额是上限，不是最终价格，最终扣费以任务结算为准。 个别账户的折扣不体现在这里，本接口给的是牌价。\n",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "book_version": 12,
                  "currency": "CNY",
                  "effective_at": "2026-09-04T00:00:00Z",
                  "image_models": [
                    {
                      "capabilities": [
                        "image_generation"
                      ],
                      "display_name": "GPT Image 2 Official",
                      "id": "gpt-image-2-official",
                      "tariff": {
                        "cached_image_input_micro_usd_per_m": 2000000,
                        "cached_text_input_micro_usd_per_m": 1250000,
                        "image_input_micro_usd_per_m": 8000000,
                        "image_output_micro_usd_per_m": 30000000,
                        "text_input_micro_usd_per_m": 5000000,
                        "version": "openai-gpt-image-2-standard-2026-09-14"
                      }
                    }
                  ],
                  "models": [
                    {
                      "capabilities": [
                        "chat",
                        "stream",
                        "tools"
                      ],
                      "display_name": "Kimi K3",
                      "id": "kimi-k3",
                      "input_per_m": 20000000,
                      "output_per_m": 100000000
                    }
                  ],
                  "unit": "micro_yuan_per_million_tokens"
                },
                "schema": {
                  "$ref": "#/components/schemas/PricingCatalog"
                }
              }
            },
            "description": "生效价目簿的公开售价",
            "headers": {
              "Cache-Control": {
                "description": "public, max-age=60",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        },
        "summary": "公开价目表（免鉴权）",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1/requests/by-client/{clientID}": {
      "get": {
        "description": "Scoped to the authenticated tenant. Missing or ambiguous correlation ids return 404. Available at zero balance. This lookup does not make POST requests idempotent.\n",
        "parameters": [
          {
            "in": "path",
            "name": "clientID",
            "required": true,
            "schema": {
              "maxLength": 64,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RequestDetail"
                }
              }
            },
            "description": "The same whitelisted receipt returned by request-id lookup"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "Find a unique receipt by the caller's X-Request-ID correlation",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1/requests/{id}": {
      "get": {
        "description": "只能查本账户的请求；别人的请求与不存在的请求同样返回 404。 `sales_amount` 是这笔请求当时的扣费（微元），永不改写；事后冲正或补扣以 `adjustments[]` 追加， 钱包里的净变化 = sales_amount − Σ(adjustments.amount 为正的退款)。 白名单字段之外的一切（上游成本、供应商、路由候选、内部拒绝原因）都不会出现。\n",
        "parameters": [
          {
            "description": "响应头 X-Request-Id / 响应体 request_id",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "adjustments": [],
                  "billable_units": {
                    "input_tokens": 87,
                    "output_tokens": 16,
                    "request_count": 1,
                    "usage_source": "upstream"
                  },
                  "created_at": "2026-09-10T08:29:51.850427Z",
                  "currency": "CNY",
                  "latency_ms": {
                    "platform_overhead": 26,
                    "total": 3042,
                    "upstream_first_byte": 3016,
                    "upstream_total": 3016
                  },
                  "model": "kimi-k3",
                  "request_id": "req_01M25700V1PHY8T8C0E3AXYX4P",
                  "route_id": "01M25700VXN86JE0GT5GPHX735",
                  "sales_amount": 3340,
                  "status": "FINALIZED",
                  "stream": false,
                  "usage": {
                    "input_tokens": 87,
                    "output_tokens": 16,
                    "total_tokens": 103
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/RequestDetail"
                }
              }
            },
            "description": "request detail (whitelisted DTO)",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "单笔请求详情（含这一笔扣了多少钱）",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1/user/balance": {
      "get": {
        "description": "读 key 所属 tenant 的钱包，同一账户的多把 key 读到同一个钱包。查询不扣费，余额为零也能查。 `available_micro_cny = balance − held + credit_limit`。四个金额都是整数微元，除以 1,000,000 得人民币元。\n",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "available_micro_cny": 188651120,
                  "balance_micro_cny": 188651120,
                  "checked_at": "2026-09-10T08:20:47.174135076Z",
                  "credit_limit_micro_cny": 0,
                  "currency": "CNY",
                  "held_micro_cny": 0,
                  "request_id": "req_01M256FCXJW6WXMC2A7H4WJY9W"
                },
                "schema": {
                  "additionalProperties": false,
                  "properties": {
                    "available_micro_cny": {
                      "description": "当前可用 = balance − held + credit_limit",
                      "type": "integer"
                    },
                    "balance_micro_cny": {
                      "description": "账面余额",
                      "type": "integer"
                    },
                    "checked_at": {
                      "description": "UTC 查询时刻",
                      "format": "date-time",
                      "type": "string"
                    },
                    "credit_limit_micro_cny": {
                      "description": "授信额度",
                      "type": "integer"
                    },
                    "currency": {
                      "const": "CNY",
                      "type": "string"
                    },
                    "held_micro_cny": {
                      "description": "进行中请求的预占",
                      "type": "integer"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "balance_micro_cny",
                    "held_micro_cny",
                    "available_micro_cny",
                    "credit_limit_micro_cny",
                    "currency",
                    "checked_at",
                    "request_id"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "tenant wallet balance in integer micro-yuan",
            "headers": {
              "X-Request-Id": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "429": {
            "$ref": "#/components/responses/Error"
          },
          "500": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "当前 key 所属账户的钱包余额",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1/user/statement": {
      "get": {
        "description": "同一快照读取钱包和全历史账本。金额均为整数微元。balance + net_spent = funding + adjustments； 预占不计入已消费。reconciliation_difference 与 held_difference 均为零表示账本与钱包一致。 查询免费，余额耗尽仍可读。只读本账户，流水按时间和编号倒序分页；不返回上游采购成本。\n",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "default": 50,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "schema": {
              "maxLength": 512,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": false,
                  "properties": {
                    "adjustments_micro_cny": {
                      "type": "integer"
                    },
                    "available_micro_cny": {
                      "type": "integer"
                    },
                    "balance_micro_cny": {
                      "type": "integer"
                    },
                    "charges_micro_cny": {
                      "type": "integer"
                    },
                    "checked_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "credit_limit_micro_cny": {
                      "type": "integer"
                    },
                    "currency": {
                      "const": "CNY",
                      "type": "string"
                    },
                    "entries": {
                      "items": {
                        "additionalProperties": false,
                        "properties": {
                          "balance_delta_micro_cny": {
                            "type": "integer"
                          },
                          "created_at": {
                            "format": "date-time",
                            "type": "string"
                          },
                          "entry_type": {
                            "enum": [
                              "TOPUP",
                              "RESERVE",
                              "CAPTURE",
                              "RELEASE",
                              "REFUND",
                              "ADJUSTMENT",
                              "COMPENSATION"
                            ],
                            "type": "string"
                          },
                          "held_delta_micro_cny": {
                            "type": "integer"
                          },
                          "id": {
                            "type": "string"
                          },
                          "key_id": {
                            "type": "string"
                          },
                          "model": {
                            "type": "string"
                          },
                          "request_id": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "entry_type",
                          "balance_delta_micro_cny",
                          "held_delta_micro_cny",
                          "created_at"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "funding_micro_cny": {
                      "type": "integer"
                    },
                    "held_difference_micro_cny": {
                      "type": "integer"
                    },
                    "held_micro_cny": {
                      "type": "integer"
                    },
                    "keys": {
                      "description": "同账户的 Key 汇总；共用同一个钱包，充值和余额不得按 Key 重复累计",
                      "items": {
                        "additionalProperties": false,
                        "properties": {
                          "current": {
                            "description": "是否为此次查询所用的 Key",
                            "type": "boolean"
                          },
                          "id": {
                            "type": "string"
                          },
                          "net_spent_micro_cny": {
                            "type": "integer"
                          },
                          "requests": {
                            "type": "integer"
                          },
                          "status": {
                            "enum": [
                              "active",
                              "disabled"
                            ],
                            "type": "string"
                          }
                        },
                        "required": [
                          "id",
                          "status",
                          "current",
                          "net_spent_micro_cny",
                          "requests"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "models": {
                      "items": {
                        "additionalProperties": false,
                        "properties": {
                          "held_micro_cny": {
                            "minimum": 0,
                            "type": "integer"
                          },
                          "images": {
                            "minimum": 0,
                            "type": "integer"
                          },
                          "model": {
                            "type": "string"
                          },
                          "net_spent_micro_cny": {
                            "type": "integer"
                          },
                          "requests": {
                            "minimum": 0,
                            "type": "integer"
                          },
                          "unconfirmed_calls": {
                            "minimum": 0,
                            "type": "integer"
                          }
                        },
                        "required": [
                          "model",
                          "requests",
                          "images",
                          "net_spent_micro_cny",
                          "held_micro_cny",
                          "unconfirmed_calls"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "net_spent_micro_cny": {
                      "type": "integer"
                    },
                    "next_cursor": {
                      "type": "string"
                    },
                    "reconciliation_difference_micro_cny": {
                      "type": "integer"
                    },
                    "refunds_micro_cny": {
                      "type": "integer"
                    },
                    "request_id": {
                      "type": "string"
                    },
                    "unattributed_model_net_spent_micro_cny": {
                      "type": "integer"
                    },
                    "unattributed_net_spent_micro_cny": {
                      "description": "无法归属 Key 的净消费（如账户级退款）；与各 Key 净消费之和等于账户净消费",
                      "type": "integer"
                    },
                    "unconfirmed_calls": {
                      "description": "结果或用量尚待核查的原生调用数",
                      "type": "integer"
                    }
                  },
                  "required": [
                    "balance_micro_cny",
                    "held_micro_cny",
                    "available_micro_cny",
                    "credit_limit_micro_cny",
                    "funding_micro_cny",
                    "adjustments_micro_cny",
                    "charges_micro_cny",
                    "refunds_micro_cny",
                    "net_spent_micro_cny",
                    "reconciliation_difference_micro_cny",
                    "held_difference_micro_cny",
                    "currency",
                    "checked_at",
                    "request_id",
                    "entries"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "同一时点的账户对账与流水"
          },
          "4XX": {
            "$ref": "#/components/responses/Error"
          },
          "5XX": {
            "$ref": "#/components/responses/Error"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "当前 key 所属账户的充值、消费、余额与流水",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1beta/invocations/{id}": {
      "get": {
        "description": "不扣费、不要求余额。同租户同 Key 才能查询。结果可恢复时返回原生生成响应； 仍在执行、结果未知或正文超过 1 MiB 无法重放时返回 409，并保留永久执行标记。 HTTP 409 本身不表示可以新建调用。\n",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "原调用的生成结果"
          },
          "4XX": {
            "description": "无可恢复结果、请求不存在或鉴权失败"
          },
          "5XX": {
            "description": "账本暂时不可读"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "恢复同一 Key 的 Gemini 调用结果（不发起生成）",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1beta/jobs/by-idempotency/{id}": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "maxLength": 128,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NativeJob"
                }
              }
            },
            "description": "Same tenant/key durable job"
          },
          "404": {
            "description": "No job visible to this key"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "Recover a job by stable Idempotency-Key (no purchase)",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1beta/jobs/{id}": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NativeJob"
                }
              }
            },
            "description": "Same tenant/key job, including terminal unknown"
          },
          "404": {
            "description": "Job not visible to this key"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "Read native job state and result without buying again",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1beta/models/{action}": {
      "post": {
        "description": "action 为 gemini-3.1-pro-preview:generateContent、gemini-2.5-pro:generateContent， 或兼容别名 gemini-3-pro-preview:generateContent（实际返回 3.1 Pro）。请求使用原生 contents/parts， 上限 96 MiB；仅文本输出、单候选，不支持 tools、显式缓存、Files 或流式。 必须提供持久稳定的 Idempotency-Key。同 key 同编号同正文最多发起一次上游生成，正文不同返回冲突。 视频预占使用模型最大输入量 1048576 和 maxOutputTokens；最终按上游 prompt、缓存和 thinking 用量结算。 超过 200000 prompt tokens 使用价目长上下文档。缺用量保留结果并免扣，不使用媒体字节长度猜 token。 X-P34-Execution-State 为 not_started/completed/unknown；unknown 不得自动新建调用，应查询原编号。 原编号不会因超时或过期重新开放采购。响应仅保留生成内容和原生 SDK 字段，不含内部成本。\n",
        "parameters": [
          {
            "in": "path",
            "name": "action",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "maxLength": 128,
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "properties": {
                  "contents": {
                    "items": {
                      "additionalProperties": true,
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "contents"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Gemini 原生结果，X-P34-Usage-State 为 reported 或 unknown"
          },
          "4XX": {
            "description": "原生 error envelope；请求编号和执行状态在响应头"
          },
          "5XX": {
            "description": "执行结果未确认；只查询原调用，不自动再次采购"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "Gemini 原生非流式生成（文本或视频输入）",
        "tags": [
          "v1"
        ]
      }
    },
    "/v1beta/models/{action}/jobs": {
      "post": {
        "description": "Native contents JSON and a stable Idempotency-Key. Returns immediately; poll Location with the same API key. Only verified not-started attempts can retry; unknown is terminal and must never trigger a new purchase. Unchanged synchronous generateContent remains available.\n",
        "parameters": [
          {
            "in": "path",
            "name": "action",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "maxLength": 128,
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "properties": {
                  "contents": {
                    "items": {
                      "additionalProperties": true,
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "contents"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NativeJob"
                }
              }
            },
            "description": "Durably accepted or replayed job"
          },
          "4XX": {
            "description": "Invalid",
            "idempotency conflict or bounded backlog full": null,
            "unauthorized": null
          },
          "5XX": {
            "description": "Job persistence unavailable"
          }
        },
        "security": [
          {
            "bearer": []
          },
          {
            "apiKey": []
          }
        ],
        "summary": "Submit durable native generation (queue-enabled deployments)",
        "tags": [
          "v1"
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://api.apipace.com"
    }
  ],
  "tags": [
    {
      "description": "客户数据面。API key 鉴权，OpenAI 与 Anthropic 双协议。",
      "name": "v1"
    }
  ]
}
