> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seedhorse.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

# Seedhorse API

Generate high-quality AI videos and images from text, images, or multimodal references with a single HTTP request. This API powers the same image and video generation engine used in NanoBanana、HappyHorse、Seedance, exposed for programmatic access.

## What you can build

* **Text-to image** - generate a 4k image from a natural-language prompt
* **Text-to-video** - generate a video from a natural-language prompt
* **Image-to-video** - animate a single image or interpolate between a first and last frame
* **Reference-to-video** - use up to 9 reference images, 3 reference videos, and 3 reference audios to guide the generation

Five model variants are available:

| Model            | Type  | Quality |
| ---------------- | ----- | ------- |
| `seedance-2.0`   | Video | Highest |
| `HappyHorse 1.0` | Video | Highest |
| `Vido Q3-Pro`    | Video | Highest |
| `NanoBanana Pro` | Image | Highest |
| `NanoBanana 2.0` | Image | Highest |
| `gpt-image 2.0`  | Image | Highest |

* Image: Supports generation of 1K, 2K and 4K ultra-high-quality images.
* Video: Both support 480p and 720p, durations of 4–30 seconds, and optional audio track generation.

> To explore more models, please visit [https://www.tkhub.ai](https://www.tkhub.ai)

## Base URL

All requests go to:

```text theme={null}
https://api.seedhorse.ai
```

Endpoints are versioned under `/api/v1`.

## Authentication

Every request must carry a Bearer token in the `Authorization` header:

```http theme={null}
Authorization: Bearer sk_xxxxxxxxxxxxxxxxxx
```

### Getting an API key

1. Sign in to your account
2. Open the **API Keys** page — <a href="https://www.seedhorse.ai/workspace/keys" target="_blank" rel="noopener noreferrer">**go there now →**</a>
3. Click **Create API Key**, give it a name, and copy the generated key

Keys are shown **only once** at creation. Store them in a secret manager; they cannot be retrieved later. You can revoke a key at any time from the same page.

### Security notes

* **Always use HTTPS.** Requests over HTTP are rejected in production.
* **Never put the key in a query string.** The server rejects any request that exposes `?api_key=...` or similar, because CDN/proxy logs may already have captured it. Rotate such a key immediately.
* **Never commit keys to git.** Use environment variables.
* **Keys are user-scoped.** An API key inherits the credit balance and data isolation of the owning user. One user's keys cannot access another user's tasks.

## Credit pricing

API calls consume credits from the authenticated user's balance. Pricing is determined by `model`, `duration`, and `resolution`

Exact amounts are deducted atomically before the task is submitted. If a task fails, the full charge is refunded automatically.

If your balance is insufficient, the request returns `402 Insufficient credits`. Top up from the **Credits** page in the studio sidebar.

## Quickstart

A complete end-to-end example. Replace `sk_xxxxx` with your real key.

### 1. Submit a task

```bash theme={null}
curl -X POST https://api.seedhorse.ai/api/v1/video/generate \
  -H "Authorization: Bearer sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "type": "text-to-video",
    "prompt": "A cat walking on the street at night",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "enable_audio": true
  }'
```

Response (HTTP 201):

```json theme={null}
{
  "id": "task_623bd250fd2b4b289c5562381918cea7",
  "status": "queued",
  "model": "seedance-2.0",
  "type": "text-to-video",
  "credits_charged": 60,
  "credits_refunded": 0,
  "created_at": "2026-04-12T15:30:00.000Z"
}
```

### 2. Poll for completion

Credits are deducted at submission time. **You must call this endpoint to obtain the final task state.** The response includes the live status on every call. Poll until `status` transitions to `succeeded` or `failed`.

```bash theme={null}
curl https://api.seedhorse.ai/api/v1/video/task/task_623bd250fd2b4b289c5562381918cea7 \
  -H "Authorization: Bearer sk_xxxxx"
```

Poll every 5–10 seconds. If the task ultimately fails, the first poll that observes the failure automatically refunds the original charge — `credits_refunded` will equal `credits_charged` in the response.

<warn>
  **A task you never poll will not auto-refund on failure.** You are responsible for polling each task you submit at least once after generation should have completed (typically 1–2 minutes after submission). See [Retrieve tasks](/docs/api/task) for details.
</warn>

### 3. Download the result

When `status` is `succeeded`, the response includes `video_url`:

```json theme={null}
{
  "id": "task_623bd250fd2b4b289c5562381918cea7",
  "status": "succeeded",
  "model": "seedance-2.0-fast",
  "type": "text-to-video",
  "credits_charged": 60,
  "credits_refunded": 0,
  "created_at": "2026-04-11T15:30:00.000Z",
  "video_url": "https://resources.seedhorse.ai/.../video.mp4"
}
```

<warn>
  Video URLs expire **24 hours** after generation. Download and persist them to your own storage immediately if you need long-term retention.
</warn>

## Next steps

* [`POST /api/v1/video/generate`](/docs/api/generate) — full request reference
* [`GET /api/v1/video/task/{id}`](/docs/api/task) — check status and retrieve results
* [Errors](/docs/api/errors) — error code reference