Skip to content

API.md

Latest commit

 

History

History
151 lines (113 loc) · 2.93 KB

API.md

File metadata and controls

151 lines (113 loc) · 2.93 KB
Raw

Sentence Knowledge Parser API Reference

Base URL:

https://lbit.bczabcd.cn

Authentication

All /api/v1/* endpoints require an API key. API keys are issued to invited users only. This API is not a public self-service account system.

Authorization: Bearer YOUR_SENTENCE_KNOWLEDGE_API_KEY

Analyze Text

POST /api/v1/analyze

Request:

{
  "text": "I agree.",
  "language": "en",
  "return_lbits": true,
  "return_parse": true
}

Supported language values:

en, ja, es

Important response fields:

{
  "analysis_status": "full_parse",
  "language": "en",
  "cache_status": "miss",
  "history_id": "result-id",
  "lbit_count_by_type": {
    "direct": { "w": 3, "ph": 2, "s": 1 },
    "prerequisite": { "w": 1, "ph": 0, "s": 0 },
    "cumulative": { "w": 4, "ph": 2, "s": 1 }
  },
  "human_lbit_summary": {
    "counts": {},
    "lbit_cards": []
  }
}

cache_status:

  • miss: generated now
  • hit: loaded from this account's saved history

The w, ph, and s counts are separate scales:

Count type Meaning
w_L-bit word-level language knowledge
ph_L-bit phrase-level language knowledge
s_L-bit sentence-level language knowledge

Do not add these three types into one weighted score unless your application defines its own weighting policy.

Generate Prerequisite L-bits

POST /api/v1/prerequisite-lbits/jobs

Prerequisite generation may call an LLM. Public API callers must bring their own LLM key. The L-bit service does not use the service owner's model key for public API calls.

If your application does not want to provide an LLM key, do not call this endpoint. Use /api/v1/analyze only and present direct L-bits. That mode is cheaper and faster, but it does not include the generated prerequisite L-bit list.

Request:

{
  "text": "How good the goal is!",
  "language": "en",
  "return_lbits": true,
  "return_parse": true,
  "llm": {
    "provider": "openai_compatible",
    "base_url": "https://ark.cn-beijing.volces.com/api/v3",
    "model": "YOUR_MODEL_NAME",
    "api_key": "YOUR_LLM_API_KEY"
  }
}

If llm.api_key or llm.model is missing, this endpoint returns:

{
  "error": "LLM_CONFIG_REQUIRED"
}

Response:

{
  "job_id": "uuid",
  "status": "pending",
  "progress": 0
}

Poll:

GET /api/v1/prerequisite-lbits/jobs/{job_id}

Final response includes prerequisite_summary.

Explain Analysis

POST /api/v1/explain

Request is the same shape as /api/v1/analyze. You may also provide llm. If llm is omitted, the endpoint returns deterministic fallback explanation text and does not call an LLM.

The response is a plain-language explanation intended for display.

Errors

Common errors:

{ "error": "API_KEY_REQUIRED" }
{ "error": "INVALID_API_KEY" }
{ "error": "INVALID_INPUT" }
{ "error": "UNSUPPORTED_LANGUAGE" }
{ "error": "JOB_NOT_FOUND" }