{
  "openapi": "3.0.0",
  "info": {
    "title": "EcoCompute should-I-quantize API",
    "version": "1.0.0",
    "description": "Deterministic estimate of weight-only quantization energy change (ΔE% vs FP16), calibrated to measured GPU data."
  },
  "paths": {
    "/v1/estimate": {
      "get": {
        "summary": "Estimate ΔE% for quantizing a model on a GPU architecture",
        "parameters": [
          {
            "name": "params_b",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "model size in billions of parameters"
          },
          {
            "name": "arch",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "turing",
                "ada",
                "blackwell",
                "ampere",
                "hopper"
              ]
            }
          },
          {
            "name": "precision",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "NF4",
                "INT8"
              ]
            }
          },
          {
            "name": "batch",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 1
            }
          },
          {
            "name": "ctx",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 2048
            }
          },
          {
            "name": "q",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "plain-English query, e.g. '13B on A100 int8 batch 32'"
          }
        ],
        "responses": {
          "200": {
            "description": "estimate"
          }
        }
      }
    },
    "/v1/architectures": {
      "get": {
        "summary": "List supported architectures, precisions and measured ranges",
        "responses": {
          "200": {
            "description": "ok"
          }
        }
      }
    },
    "/v1/optimize": {
      "get": {
        "summary": "Recommend the objective-optimal (precision, batch, context) under latency/VRAM/throughput constraints",
        "description": "Exhaustive constrained search. Energy is measured-anchored; latency/throughput are a roofline MODEL; VRAM is computed. Every config carries per-field basis + confidence.",
        "parameters": [
          {
            "name": "params_b",
            "in": "query",
            "required": true,
            "schema": {
              "type": "number"
            },
            "description": "model size in billions of parameters"
          },
          {
            "name": "arch",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "turing",
                "ada",
                "blackwell",
                "ampere",
                "hopper"
              ]
            }
          },
          {
            "name": "objective",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "min_energy",
                "min_latency",
                "max_throughput",
                "min_vram"
              ],
              "default": "min_energy"
            }
          },
          {
            "name": "max_latency_ms",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "latency budget, ms per token"
          },
          {
            "name": "max_vram_gb",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "VRAM budget in GB"
          },
          {
            "name": "min_throughput",
            "in": "query",
            "schema": {
              "type": "number"
            },
            "description": "throughput floor, tokens/s"
          },
          {
            "name": "batch",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "pin batch size (else searched)"
          },
          {
            "name": "context",
            "in": "query",
            "schema": {
              "type": "integer"
            },
            "description": "pin context length (else searched)"
          }
        ],
        "responses": {
          "200": {
            "description": "recommended config, alternatives and energy/latency Pareto front"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://ecocompute-estimator.zhanghongping1982.workers.dev"
    }
  ]
}