docs: update and optimize README and project documentation system
- Update README.md with improved formatting, logo, badges, and comprehensive documentation - Add README.en.md with English translation of the documentation - Include detailed quick start guide, CLI reference, and supported models table - Add changelog information highlighting recent features - Add script directory and adjust script file locations
This commit is contained in:
XiaoYang
+461
@@ -0,0 +1,461 @@
|
||||
# API Reference
|
||||
|
||||
Complete reference for the AHA REST API.
|
||||
|
||||
## Overview
|
||||
|
||||
AHA provides an OpenAI-compatible REST API for running AI model inference. All endpoints follow standard HTTP conventions and return JSON responses.
|
||||
|
||||
### Base URL
|
||||
|
||||
By default, the API server runs on:
|
||||
```
|
||||
http://127.0.0.1:10100
|
||||
```
|
||||
|
||||
You can customize this when starting the service:
|
||||
```bash
|
||||
aha cli -m qwen3-0.6b -a 0.0.0.0 -p 8080
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
Currently, AHA does not require authentication. All endpoints are publicly accessible on the configured address/port.
|
||||
|
||||
**Security Note**: If you expose the API to external networks, consider implementing authentication through a reverse proxy (e.g., nginx, traefik).
|
||||
|
||||
### Content Types
|
||||
|
||||
All requests should use:
|
||||
```
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
### Response Format
|
||||
|
||||
Success responses follow this structure:
|
||||
```json
|
||||
{
|
||||
"data": { ... },
|
||||
"model": "model-name",
|
||||
"usage": {
|
||||
"prompt_tokens": 10,
|
||||
"completion_tokens": 20,
|
||||
"total_tokens": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Error responses:
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "Error description",
|
||||
"type": "error_type",
|
||||
"code": "error_code"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
|
||||
### Chat Completions
|
||||
|
||||
Generate chat completions or text responses.
|
||||
|
||||
#### Endpoint
|
||||
```
|
||||
POST /chat/completions
|
||||
```
|
||||
|
||||
#### Request Body
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `model` | string | Yes | Model identifier (e.g., "qwen3-0.6b") |
|
||||
| `messages` | array | Yes | Array of message objects |
|
||||
| `temperature` | number | No | Sampling temperature (0-2, default: 1) |
|
||||
| `top_p` | number | No | Nucleus sampling (0-1, default: 1) |
|
||||
| `max_tokens` | integer | No | Maximum tokens to generate |
|
||||
| `stream` | boolean | No | Enable streaming (default: false) |
|
||||
|
||||
#### Message Object
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| `role` | string | Yes | "system", "user", or "assistant" |
|
||||
| `content` | string/array | Yes | Message content (string or multimodal array) |
|
||||
|
||||
#### Multimodal Content
|
||||
|
||||
For vision/audio models, content can be an array:
|
||||
|
||||
```json
|
||||
{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "text", "text": "Describe this image"},
|
||||
{"type": "image_url", "image_url": {"url": "file:///path/to/image.jpg"}}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Supported content types:
|
||||
- `text` - Text content
|
||||
- `image_url` - Image file (file://, base64://, or http://)
|
||||
- `audio_url` - Audio file (file:// or base64://)
|
||||
|
||||
#### Examples
|
||||
|
||||
**Simple Chat:**
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:10100/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "qwen3-0.6b",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Hello!"}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
**With System Message:**
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:10100/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "qwen3-0.6b",
|
||||
"messages": [
|
||||
{"role": "system", "content": "You are a helpful assistant."},
|
||||
{"role": "user", "content": "Explain Rust in one sentence."}
|
||||
],
|
||||
"max_tokens": 50,
|
||||
"temperature": 0.7
|
||||
}'
|
||||
```
|
||||
|
||||
**Vision Understanding:**
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:10100/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "qwen3vl-2b",
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "text", "text": "What is in this image?"},
|
||||
{"type": "image_url", "image_url": {"url": "file:///path/to/image.jpg"}}
|
||||
]
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
**OCR (Text Extraction):**
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:10100/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "deepseek-ocr",
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "text", "text": "Extract all text"},
|
||||
{"type": "image_url", "image_url": {"url": "file:///path/to/document.png"}}
|
||||
]
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
**ASR (Speech Recognition):**
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:10100/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "glm-asr-nano-2512",
|
||||
"messages": [
|
||||
{
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "text", "text": "Transcribe this audio"},
|
||||
{"type": "audio_url", "audio_url": {"url": "file:///path/to/audio.wav"}}
|
||||
]
|
||||
}
|
||||
]
|
||||
}'
|
||||
```
|
||||
|
||||
**Streaming Response:**
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:10100/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "qwen3-0.6b",
|
||||
"messages": [
|
||||
{"role": "user", "content": "Tell me a story"}
|
||||
],
|
||||
"stream": true
|
||||
}'
|
||||
```
|
||||
|
||||
Streaming responses are sent as Server-Sent Events (SSE):
|
||||
```
|
||||
data: {"id": "1", "choices": [{"delta": {"content": "Once"}}]}
|
||||
|
||||
data: {"id": "1", "choices": [{"delta": {"content": " upon"}}]}
|
||||
|
||||
data: [DONE]
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
**Non-streaming:**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "chatcmpl-123",
|
||||
"object": "chat.completion",
|
||||
"created": 1677652288,
|
||||
"model": "qwen3-0.6b",
|
||||
"choices": [
|
||||
{
|
||||
"index": 0,
|
||||
"message": {
|
||||
"role": "assistant",
|
||||
"content": "Hello! How can I help you today?"
|
||||
},
|
||||
"finish_reason": "stop"
|
||||
}
|
||||
],
|
||||
"usage": {
|
||||
"prompt_tokens": 10,
|
||||
"completion_tokens": 9,
|
||||
"total_tokens": 19
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Supported Models
|
||||
|
||||
- Text: `qwen3-0.6b`, `minicpm4-0.5b`
|
||||
- Vision: `qwen2.5vl-3b`, `qwen2.5vl-7b`, `qwen3vl-2b`, `qwen3vl-4b`, `qwen3vl-8b`, `qwen3vl-32b`
|
||||
- OCR: `deepseek-ocr`, `hunyuan-ocr`, `paddleocr-vl`
|
||||
- ASR: `glm-asr-nano-2512`, `fun-asr-nano-2512`, `qwen3asr-0.6b`, `qwen3asr-1.7b`
|
||||
|
||||
### Audio Speech
|
||||
|
||||
Generate speech from text (Text-to-Speech).
|
||||
|
||||
#### Endpoint
|
||||
```
|
||||
POST /audio/speech
|
||||
```
|
||||
|
||||
#### Request Body
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `model` | string | Yes | Model identifier (e.g., "voxcpm1.5") |
|
||||
| `input` | string | Yes | Text to convert to speech |
|
||||
| `voice` | string | No | Voice selection (default: "default") |
|
||||
|
||||
#### Example
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:10100/audio/speech \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "voxcpm1.5",
|
||||
"input": "你好，世界！",
|
||||
"voice": "default"
|
||||
}' \
|
||||
--output speech.wav
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
Returns audio data in WAV format.
|
||||
|
||||
#### Supported Models
|
||||
|
||||
- `voxcpm`, `voxcpm1.5`
|
||||
|
||||
### Images Remove Background
|
||||
|
||||
Remove background from images.
|
||||
|
||||
#### Endpoint
|
||||
```
|
||||
POST /images/remove_background
|
||||
```
|
||||
|
||||
#### Request Body
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| `model` | string | Yes | Model identifier (e.g., "rmbg2.0") |
|
||||
| `image` | string | Yes | Image file path (file://) or base64 data |
|
||||
|
||||
#### Example
|
||||
|
||||
**From File:**
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:10100/images/remove_background \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "rmbg2.0",
|
||||
"image": "file:///path/to/photo.png"
|
||||
}' \
|
||||
--output no-background.png
|
||||
```
|
||||
|
||||
**From Base64:**
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:10100/images/remove_background \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "rmbg2.0",
|
||||
"image": "base64://$(base64 -w 0 photo.png)"
|
||||
}' \
|
||||
--output no-background.png
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
Returns the processed image in PNG format.
|
||||
|
||||
#### Supported Models
|
||||
|
||||
- `rmbg2.0`
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Error Codes
|
||||
|
||||
| Code | Description |
|
||||
|------|-------------|
|
||||
| 400 | Bad Request - Invalid parameters |
|
||||
| 404 | Not Found - Model or endpoint not found |
|
||||
| 500 | Internal Server Error - Model inference error |
|
||||
| 503 | Service Unavailable - Model not loaded |
|
||||
|
||||
### Error Response Format
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"message": "Model 'unknown-model' not found",
|
||||
"type": "invalid_request_error",
|
||||
"code": "model_not_found"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
Currently, AHA does not implement rate limiting. The server can handle concurrent requests limited only by system resources.
|
||||
|
||||
## File Upload Limits
|
||||
|
||||
- String data: 5 MB
|
||||
- File uploads: 100 MB
|
||||
|
||||
## OpenAI Compatibility
|
||||
|
||||
AHA's API is designed to be compatible with OpenAI's API format. This means you can use existing OpenAI client libraries with minimal changes:
|
||||
|
||||
### Python Example
|
||||
|
||||
```python
|
||||
from openai import OpenAI
|
||||
|
||||
client = OpenAI(
|
||||
base_url="http://127.0.0.1:10100",
|
||||
api_key="dummy" # Not used but required by library
|
||||
)
|
||||
|
||||
response = client.chat.completions.create(
|
||||
model="qwen3-0.6b",
|
||||
messages=[
|
||||
{"role": "user", "content": "Hello!"}
|
||||
]
|
||||
)
|
||||
|
||||
print(response.choices[0].message.content)
|
||||
```
|
||||
|
||||
### JavaScript Example
|
||||
|
||||
```javascript
|
||||
import OpenAI from 'openai';
|
||||
|
||||
const client = new OpenAI({
|
||||
baseURL: 'http://127.0.0.1:10100',
|
||||
apiKey: 'dummy' // Not used but required
|
||||
});
|
||||
|
||||
const response = await client.chat.completions.create({
|
||||
model: 'qwen3-0.6b',
|
||||
messages: [{ role: 'user', content: 'Hello!' }]
|
||||
});
|
||||
|
||||
console.log(response.choices[0].message.content);
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Use Streaming for Long Responses
|
||||
|
||||
For long text generation, use streaming to get responses incrementally:
|
||||
|
||||
```bash
|
||||
curl ... -d '{"stream": true, ...}'
|
||||
```
|
||||
|
||||
### 2. Set Appropriate Token Limits
|
||||
|
||||
Prevent excessively long responses:
|
||||
|
||||
```json
|
||||
{
|
||||
"max_tokens": 500
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Adjust Temperature
|
||||
|
||||
Control response creativity:
|
||||
- `0.0-0.3`: Deterministic, focused
|
||||
- `0.4-0.7`: Balanced (default: 1.0)
|
||||
- `0.8-2.0`: Creative, varied
|
||||
|
||||
### 4. Use System Messages
|
||||
|
||||
Set behavior with system messages:
|
||||
|
||||
```json
|
||||
{
|
||||
"messages": [
|
||||
{"role": "system", "content": "You are a technical writer."},
|
||||
{"role": "user", "content": "..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Getting Started](./getting-started.md) - Quick start guide
|
||||
- [CLI Reference](./cli.md) - Command-line usage
|
||||
- [Installation](./installation.md) - Installation guide
|
||||
- [Development](./development.md) - Contributing guide
|
||||
Reference in New Issue
Block a user