API.md

Endpoint

Evaluate writing

POST /call/evaluate

说明：

Evaluate IELTS writing or letter text. Returns grammar correction, grammar score, coherence score and suggestions.

---

Request

Content-Type

application/json

Body

{
  "data": [
    "Your IELTS writing text here"
  ]
}

说明：

Field	Type	Description
data[0]	string	IELTS writing text

---

Example Request (curl)

curl -X POST https://你的用户名-你的space名.hf.space/call/evaluate \
-H "Content-Type: application/json" \
-d '{"data":["I think university student should learn practical skill because it help their future job."]}'

---

Example Request (Python)

from gradio_client import Client

client = Client("你的用户名/你的space名")

result = client.predict(
    "I think university student should learn practical skill because it help their future job.",
    api_name="/evaluate"
)

print(result)

---

Response

示例返回：

{
  "original_text": "I think university student should learn practical skill because it help their future job.",
  "corrected_text": "I think university students should learn practical skills because it helps their future jobs.",
  "grammar_score": 6.0,
  "coherence_score": 6.5,
  "suggestions": [
    "Revise grammar carefully. There are noticeable language errors.",
    "Add more linking words to improve flow."
  ]
}

---

Response Fields

Field	Type	Description
original_text	string	Original input text
corrected_text	string	Grammar corrected version
grammar_score	float	Estimated grammar score (0-9)
coherence_score	float	Estimated coherence score (0-9)
suggestions	list[string]	Writing improvement suggestions

---

Score Meaning

Grammar Score

Score	Meaning
8-9	Very few grammar errors
6-7	Some grammar issues
4-5	Frequent grammar problems
<4	Major grammar errors

Coherence Score

Score	Meaning
7-8	Good paragraph structure and linking
6	Basic logical structure
4-5	Weak organization

Note:

Scores are heuristic estimates, not official IELTS band scores.

---

Limits (当前版本)

Limit	Value
Max text length	~1000 words
Response time	3-15 seconds
Auth	None (public demo)

---

Error Response

Example

{
  "error": "Input cannot be empty."
}

---

Recommended Usage

Suitable for:

• IELTS writing practice apps
• English learning apps
• Grammar correction tools
• Writing assistant tools

Not suitable for:

• official IELTS scoring
• high-stakes evaluation

---

下一步建议

你现在这个 API 文档已经 够 MVP 产品用了。

但如果你准备做一个 真正的 IELTS Writing App，我强烈建议下一步升级 API：

增加：

task_response_score
lexical_score
overall_band

最终变成：

overall_band
grammar_score
coherence_score
lexical_score
task_response_score

这就和 IELTS 的评分维度基本一致。