# Horacle AI - Developer API

> Horacle is an AI media generation platform exposing a unified REST API for images, videos, audio, talking avatars (HeyGen), voice cloning/design, and visual workflows. Authentication uses Bearer API keys (`hk_live_...`). All endpoints are async (fire + poll).

This file follows the [llms.txt](https://llmstxt.org) convention so AI agents can fetch the API surface without executing JavaScript. The human-facing docs at https://app.horacle.ai/developers are a React SPA — fetch this file or the OpenAPI spec instead.

## Base URL

```
https://auth.horacle.ai/functions/v1/public-api
```

## Authentication

All requests require a Bearer token issued from the Horacle dashboard:

```
Authorization: Bearer hk_live_YOUR_KEY
Content-Type: application/json
```

Get a key: https://app.horacle.ai/user-panel/account

## Async Pattern (fire + poll)

Every generation endpoint returns a `generationId` (or `task_id`). Poll `GET /generations/{id}` every 5–10s until `status === "completed"`.

```bash
# 1. Fire
POST /images/generate  →  { "generationId": "uuid", "status": "processing" }

# 2. Poll
GET  /generations/uuid →  { "status": "completed", "result_url": "https://..." }
```

Polling times: images 15–25s · video 5s 60–90s · video 10s 120–180s · veo-3.1 120–240s · sora-2 180–300s · TTS 5–10s · lipsync 60–90s.

## Models (live catalog)

Always fetch the authoritative list:

```
GET https://auth.horacle.ai/functions/v1/public-api/models
```

### Images
- `nano-banana` — 15 cr · fast, T2I + I2I (max 4 refs)
- `nano-banana-2` — 40 cr · improved quality, T2I + I2I
- `nano-banana-pro` — 50 cr · highest nano-banana tier
- `gpt-image-2` — 60 cr · photorealism + text rendering, T2I + I2I (max 16 reference images)
- `flux-2-pro` — 45 cr · photorealistic flux
- `flux-2-flex` — 30 cr · flexible flux variant
- `seedream` — 15 cr · stylized
- `seedream-v4.5` — 45 cr · latest seedream

### Videos
- `kling-2.6` — 150 cr · balanced T2V + I2V, 5–10s
- `kling-v3` — 450–2010 cr · top-tier kling, character consistency
- `kling-omni` — 450–2010 cr · multi-shot kling
- `kling-motion-control` — 18 cr/s · motion-conditioned
- `seedance-1.5` — 120 cr · motion/dance specialist
- `veo-3.1-fast` / `veo-3.1-quality` — 560 cr · cinematic 8s
- `sora-2-pro` — 90–168 cr · creative
- `sora-2-pro-hd` — 495–945 cr · HD creative
- `wan-2.6` — 120 cr · artistic style

### Audio
- `eleven_multilingual_v2`, `eleven_turbo_v2_5` — TTS
- ElevenLabs voices: `GET /audio/voices` (premium + cloned + designed)
- Voice cloning: `POST /audio/voice-clone` (multipart, ≥30s clean audio)
- Voice design: `POST /audio/voice-design` → preview → `POST /audio/voice-design/save`

### Talking avatars (HeyGen)
- `GET /heygen/avatars` · `GET /heygen/voices`
- `POST /heygen/generate` · `POST /heygen/translate` · `GET /heygen/status`

## Endpoint reference

### Generation
- `POST /images/generate` — text-to-image / image-to-image
- `POST /images/upscale` — upscale image
- `POST /images/upload` — upload image (returns public URL)
- `POST /images/analyze` — describe image
- `POST /images/to-prompt` — reverse engineer a prompt
- `POST /videos/generate` — T2V / I2V (pass `image_url` for I2V)
- `POST /videos/upscale` — upscale video
- `POST /videos/lipsync` — lipsync (frontal portrait + audio)
- `POST /videos/motion-control` — motion-conditioned video
- `POST /videos/merge` — concat clips
- `POST /videos/trim` · `POST /videos/speed` · `POST /videos/probe`
- `POST /audio/tts` — text to speech
- `POST /audio/stt` — speech to text (dynamic per-second pricing)
- `POST /audio/music` · `POST /audio/generate` — music generation
- `POST /audio/trim` · `POST /audio/voice-change`
- `POST /audio/voice-clone` · `POST /audio/voice-design` · `POST /audio/voice-design/save`

### Orchestration
- `POST /workflows/generate` — NL → workflow JSON
- `POST /workflows/create` — save workflow
- `GET /workflows` · `GET /workflows/schema` · `GET /workflow-runs`
- `POST /campaigns/video` — multi-video campaign
- `POST /batch/generate` — parallel variations
- `POST /prompts/optimize` — prompt enhancement

### HeyGen avatars
- `GET /heygen/avatars` · `GET /heygen/voices` · `GET /heygen/status`
- `POST /heygen/generate` · `POST /heygen/translate`

### Conversational AI (ElevenLabs ConvAI)
- `POST /conversations/token` — get WebRTC/WebSocket token
- `POST /conversations/end` — close session

### Characters
- `GET /characters` · `GET /characters/search`

### Uploads
- `POST /uploads/create-link` — image upload link
- `POST /uploads/create-audio-link` — audio upload link
- `POST /uploads/create-video-link` — video upload link

### Status & utility
- `GET /generations/{generation_id}` — poll generation status
- `GET /generations` — list generations
- `GET /credits/balance` — current credit balance
- `GET /audio/voices` · `GET /voices`
- `GET /models` — live model catalog

### Webhooks
- `POST /webhooks` · `GET /webhooks` — manage webhooks (push notifications instead of polling)

## Quick examples

### Generate an image (gpt-image-2 with reference)

```bash
curl -X POST https://auth.horacle.ai/functions/v1/public-api/images/generate \
  -H "Authorization: Bearer hk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Editorial portrait, soft window light, 35mm film grain",
    "aspect_ratio": "1:1",
    "reference_images": ["https://example.com/ref.jpg"]
  }'
```

### Generate a video (I2V)

```bash
curl -X POST https://auth.horacle.ai/functions/v1/public-api/videos/generate \
  -H "Authorization: Bearer hk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-2.6",
    "prompt": "Subtle camera push-in, product slowly rotating",
    "image_url": "https://example.com/product.jpg",
    "duration": 5,
    "aspect_ratio": "9:16"
  }'
```

### Poll status

```bash
curl https://auth.horacle.ai/functions/v1/public-api/generations/GEN_ID \
  -H "Authorization: Bearer hk_live_YOUR_KEY"
```

### Text-to-speech

```bash
curl -X POST https://auth.horacle.ai/functions/v1/public-api/audio/tts \
  -H "Authorization: Bearer hk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to Horacle.",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "model": "eleven_multilingual_v2"
  }'
```

## Error handling

- `401 unauthorized` — bad/missing API key
- `402 insufficient_credits` — top up via dashboard
- `422 content_policy` — reformulate the prompt
- `429 rate_limited` — back off 30s and retry
- `5xx` — retry with exponential backoff (max 3)

Failed generations are auto-detected and refunded by the platform's recovery system; no manual action needed in most cases.

## MCP integration (Claude / Cursor / etc.)

Horacle ships a native Model Context Protocol server:

```
https://auth.horacle.ai/functions/v1/mcp-server
```

OAuth 2.0 + API key auth. 55+ tools covering every endpoint above. Add it to Claude Desktop / Cursor as an MCP server and the agent can fire generations directly.

## Resources

- OpenAPI 3.1 spec: https://auth.horacle.ai/functions/v1/public-api/openapi.json
- Live model catalog: https://auth.horacle.ai/functions/v1/public-api/models
- Workflow schema: https://auth.horacle.ai/functions/v1/public-api/workflows/schema
- Human docs (SPA): https://app.horacle.ai/developers
- Dashboard: https://app.horacle.ai/user-panel
- API keys: https://app.horacle.ai/user-panel/account