aha/docs/api.md

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:

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:

{
  "data": { ... },
  "model": "model-name",
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

Error responses:

{
  "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:

{
  "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:

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:

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:

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):

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):

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:

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:

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

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:

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:

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

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

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

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:

curl ... -d '{"stream": true, ...}'

2. Set Appropriate Token Limits

Prevent excessively long responses:

{
  "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:

{
  "messages": [
    {"role": "system", "content": "You are a technical writer."},
    {"role": "user", "content": "..."}
  ]
}

See Also

• Getting Started - Quick start guide
• CLI Reference - Command-line usage
• Installation - Installation guide
• Development - Contributing guide