README.md

---
title: Irodori TTS StackChan API
emoji: 🔊
colorFrom: gray
colorTo: blue
sdk: docker
app_port: 7860
suggested_hardware: cpu-basic
---

# Irodori TTS StackChan API

TTS QUEST compatible adapter for StackChan.

## Role

This public CPU Basic Space exposes a simple HTTP API for StackChan and forwards synthesis requests to the private Irodori-TTS ZeroGPU Space.

## Endpoint

```text
GET /synthesis
```

Parameters:

- `key`: required when `TTS_API_KEY` is configured
- `text`: text to synthesize
- `speaker`: logical speaker key. Default is `3`
- `seconds`: optional. Leave empty or set `auto` for automatic duration
- `duration_scale`: optional duration predictor scale. Default is `0.95`
- `steps`: diffusion steps. Default is `18`
- `seed`: optional. Leave empty for stable per-speaker seed
- `caption`: optional VoiceDesign prompt. Defaults to the StackChan voice style

Example:

```bash
curl 'https://schroneko-irodori-tts-stackchan-api.hf.space/synthesis?key=YOUR_KEY&text=%E3%81%93%E3%82%93%E3%81%AB%E3%81%A1%E3%81%AF&speaker=3&steps=18&duration_scale=0.95'
```

Response shape:

```json
{
  "success": true,
  "isApiKeyValid": true,
  "speaker": "3",
  "seed": "4683784571875087395",
  "durationScale": 0.95,
  "metadata": {
    "checkpoint_repo": "Aratako/Irodori-TTS-600M-v3-VoiceDesign",
    "reference_used": true,
    "reference_path": "reference/stackchan-reference.mp3",
    "caption_used": true
  },
  "mp3StreamingUrl": "https://...",
  "mp3DownloadUrl": "https://...",
  "audioStatusUrl": "https://..."
}
```

StackChan should play `mp3StreamingUrl`.

## Health Check

```bash
curl 'https://schroneko-irodori-tts-stackchan-api.hf.space/health'
```

## Environment

Required secrets:

- `HF_TOKEN`: token used to access the private ZeroGPU Space
- `TTS_API_KEY`: shared API key for callers

Configuration:

- `ZERO_SPACE`: default `schroneko/irodori-tts-zerogpu`
- `PUBLIC_BASE_URL`: public API base URL
- `DEFAULT_SECONDS`: use `auto` for automatic duration
- `DEFAULT_DURATION_SCALE`: default `0.95`
- `DEFAULT_STEPS`: default `18`
- `DEFAULT_SEED`: default `3407`
- `DEFAULT_CAPTION`: default StackChan VoiceDesign prompt
- `MAX_TEXT_LENGTH`: default `240`

## Cost

The intended deployment is:

- Adapter: CPU Basic, free
- Generation backend: ZeroGPU, free quota

Dedicated GPU hardware such as T4, L4, A10G, A100, or H200 is not required for this setup.

## Troubleshooting

If text is cut off, remove the `seconds` parameter or set it to `auto`.

If the voice changes too much between prompts, update the reference voice in the private ZeroGPU Space with a longer clean sample.

If the adapter returns `502`, check the private ZeroGPU Space logs first.