# Cliprise Business API (markdown mirror)

**Summary:** The **Cliprise Business API** exposes a **REST** integration for **asynchronous** AI **image**, **video**, and **audio** generation (plus related media workflows) through **two endpoints** on **`business.api.cliprise.app`**. Integrators **POST** a job, receive a **`taskId`**, then **poll** **GET** status until completion or failure. The public catalog documents **55 entries**: **54 primary routes** and **1 compatibility alias** (`kling-2-5` → use `kling-video-turbo` for new work). By modality in the catalog: **21 image**, **27 video**, **6 audio** routes. Request shapes split into **48 standard-input** (nested `input` object) and **6 root-only** (fields at JSON body root, no `input`).

**Canonical HTML documentation:** https://www.cliprise.app/docs/cliprise-api-docs.html  
**Machine-readable catalog:** https://www.cliprise.app/docs/cliprise-api-catalog.csv  

---

## Base URL and host

- **HTTPS host:** `business.api.cliprise.app`
- **Required:** `Host` header must be **exactly** `business.api.cliprise.app`. Other hosts (IPs, wrong subdomains) → **HTTP 400** with **empty body** or `{"msg":"method_not_allowed"}`.

---

## Authentication

| Endpoint | Mechanism |
|----------|-----------|
| **Generate** | `Authorization: Bearer <CLIPRISE_API_KEY>` |
| **Status** | Query parameters `apiKey=<KEY>` and `taskId=<ID>` |

---

## Generate endpoint

- **Method:** `POST`
- **URL:** `https://business.api.cliprise.app/app/cliprise/generate`
- **Headers:** `Authorization: Bearer …`, `Content-Type: application/json`

### Core body fields

| Field | Notes |
|-------|--------|
| `model` | Catalog model id or **routed** variant (e.g. `flux-kontext-pro`, `seedance-v1-lite`, `hailuo-2-3-standard`) per model card. |
| `callBackUrl` | HTTPS URL stored with the task. **Not guaranteed delivery** — always poll. |
| `input` | **Required** for standard-input models; **omit** for root-only models (all fields at root). |
| `options` | When used: **stringified JSON object**, not a nested JSON object. |
| `imageURLList` | When used: **stringified JSON array** of image URL strings at body root. |
| `videoURLList` | When used: **stringified JSON array** of video URL strings at body root. |

### Success response

- Example: `[{"code": 200, "taskId": "…"}]` — parse defensively (`Array[0].taskId` vs `.taskId`).

### Application-level errors

- Some failures return **HTTP 200** with JSON `code: 400` and `msg` — **always inspect body `code`**, not only HTTP status.

---

## Status endpoint

- **Method:** `GET`
- **URL:** `https://business.api.cliprise.app/app/cliprise/status`
- **Query:** `apiKey`, `taskId`; optional `download=true` (string) for **binary** response.

### States (typical)

| State | HTTP | Notes |
|-------|------|--------|
| Processing | **300** | `{"status":"processing"}` — keep polling |
| Complete | **200** | JSON with result metadata / `fileURL`, or raw bytes if `download=true` |
| Failed | **400** | `failMsg` etc. |
| Bad key / task | **400** | e.g. `invalid_api_key`, `invalid_taskId` |

### Result URLs

- Treat **`fileURL`** (and similar delivery URLs) as **temporary**. **Persist** assets to your own storage if you need durability.

---

## Async flow (recommended)

1. POST generate → obtain `taskId`.  
2. Poll GET status with exponential backoff until HTTP **200** (success) or **400** (failure).  
3. On success, fetch or download output; **store** in your infrastructure.

---

## Callback + polling

- `callBackUrl` is **optional insurance**, not a replacement for polling.  
- Callback handler: **public HTTPS**, respond **200** quickly, **idempotent** per `taskId`, offload heavy work to a queue.

---

## Input type rules

- **Standard-input:** Model-specific fields live under `input: { … }`.  
- **Root-only:** No `input`; `prompt`, `options`, `imageURLList`, etc. sit at the **root** (see HTML docs per model).  
- **Tier selection:** Some families use **`options`** with a **base** catalog id (`flux-2`, `imagen-v4`); others require the **routed** `model` string — follow each **model card** in the HTML docs or CSV.

---

## Media URL requirements

- Source **image/video/audio** URLs must be **direct public** `http://` or `https://` **file** links the API can fetch **without** login, client session dependencies, browser-only share pages, or private-network access. Presigned URLs are OK if valid long enough for the job to start.

---

## Catalog scale (public doc)

- **55** documented entries = **54** primary + **1** alias.  
- **21** image, **27** video, **6** audio.  
- **48** standard-input, **6** root-only.

Full per-model parameters, enums, and credits: **HTML docs** + **CSV**.

---

## Billing (API)

- **API credits** are a **separate** balance from **app subscription** credits.  
- Public pack examples: **$9.99 → 1,300**; **$49 → 6,500**; **$99 → 13,200**; **$199 → 26,500** API credits.

---

## Official links

- HTML API docs: https://www.cliprise.app/docs/cliprise-api-docs.html  
- CSV catalog: https://www.cliprise.app/docs/cliprise-api-catalog.csv  
- Developer hub: https://www.cliprise.app/developers/api  
- LLM API guide: https://www.cliprise.app/llms-api.txt  
- JSON facts: https://www.cliprise.app/api/llm-data  

**Markdown mirror (this document):** https://www.cliprise.app/docs/cliprise-api-docs.md  

---
*Last updated: 2026-04-08. For authoritative tables and every model card, use the HTML documentation and CSV above.*