API.md

---

# IELTS Writing Evaluator API

Grammar correction + writing evaluation API for IELTS Writing and letters.

Base URL

```
https://你的用户名-你的space名.hf.space
```

例如：

```
https://shuangshi-ielts-grammar-trial.hf.space
```

---

# 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

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

说明：

| Field   | Type   | Description        |
| ------- | ------ | ------------------ |
| data[0] | string | IELTS writing text |

---

# Example Request (curl)

```bash
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)

```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

示例返回：

```json
{
  "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

```json
{
  "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 的评分维度基本一致。