# Cheap.dev AI Media API

Teaches Codex, Claude Code, and other coding agents how to use the low-cost Cheap.dev AI media API.

## Authentication
Use `Authorization: Bearer <API_TOKEN>` for all requests.
- Base URL: https://cheap.dev
- OpenAPI JSON: https://cheap.dev/openapi.json
- Model catalog: https://cheap.dev/model

## AI Quickstart
1. Create an API token at [A2E Account > API Token](https://video.a2e.ai/account/token).
2. Load the machine-readable OpenAPI spec from `https://cheap.dev/openapi.json`.
3. Use the endpoint catalog below to choose the correct media workflow.

## API Catalog

### Image & Video Generation
#### Image to Video

##### POST /api/v1/userImage2Video/start — Start image to video conversion
Convert an image to video using AI generation with custom prompts. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImage2VideoStart`
- JSON body fields:
  - `name` (body, optional; string; example: `My Image Animation`) — Name of the image to video task
  - `image_url` (body, required; string; example: `https://example.com/image.jpg`) — URL of the source image
  - `prompt` (body, optional; string; example: `Make the person in the image wave their hand`) — Generation prompt
  - `negative_prompt` (body, optional; string; example: `blurry, distorted, static`) — Negative prompt to avoid unwanted features
  - `lora` (body, optional; string) — Lora ID. If provided, prompt/negative_prompt can be omitted (prompt will be overwritten by lora preset on backend).
  - `model_type` (body, optional; string; allowed: `GENERAL`, `FLF2V`; default: `GENERAL`) — Model type for generation
  - `end_image_url` (body, optional; string; example: `https://example.com/end_image.jpg`) — End image URL (required for FLF2V model)
  - `extend_prompt` (body, optional; boolean; default: `true`) — Whether to extend the prompt automatically
  - `number_of_images` (body, optional; integer; default: `1`; min: 1; max: 8; example: `1`) — Number of videos to generate at once
  - `video_time` (body, optional; integer; default: `5`; min: 5; max: 20; example: `5`) — Video time in seconds (5, 10, 15, or 20 seconds)
  - `video_length` (body, optional; integer; min: 1; max: 1000; example: `81`) — (Deprecated) Video length in frames. Prefer video_time. Backend converts frames to seconds internally.
  - `skip_face_enhance` (body, optional; boolean; default: `false`) — Whether to skip face similarity enhancement. Defaults to false (enhancing face similarity).
  - `minor_suspected_skip` (body, optional; boolean; default: `false`) — If suspected minor is detected (10 <= age < 15), set to true to acknowledge and proceed
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userImage2Video/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Image Animation",
  "image_url": "https://example.com/image.jpg",
  "prompt": "Make the person in the image wave their hand",
  "negative_prompt": "blurry, distorted, static",
  "model_type": "GENERAL",
  "end_image_url": "https://example.com/end_image.jpg",
  "extend_prompt": true,
  "number_of_images": 1,
  "video_time": 5,
  "video_length": 81,
  "skip_face_enhance": false,
  "minor_suspected_skip": false,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Image to video task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userImage2Video/allRecords — List all records
allRecords - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserImage2VideoAllRecords`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userImage2Video/allRecords" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userImage2Video/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImage2VideoBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userImage2Video/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userImage2Video/avgProcessingTime — Get average processing time
avgProcessingTime - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserImage2VideoAvgProcessingTime`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userImage2Video/avgProcessingTime" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userImage2Video/unlimitedQueueLevel — UnlimitedQueueLevel
unlimitedQueueLevel - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserImage2VideoUnlimitedQueueLevel`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userImage2Video/unlimitedQueueLevel" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userImage2Video/{_id}/markShared — Mark record as shared
markShared - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImage2VideoIdMarkShared`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userImage2Video/507f1f77bcf86cd799439011/markShared" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userImage2Video/{_id}/markDownloaded — Mark record as downloaded
markDownloaded - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImage2VideoIdMarkDownloaded`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userImage2Video/507f1f77bcf86cd799439011/markDownloaded" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userImage2Video/{_id}/markCopied — Mark record as copied
markCopied - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImage2VideoIdMarkCopied`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userImage2Video/507f1f77bcf86cd799439011/markCopied" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userImage2Video/{_id} — Get record details
detail - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserImage2VideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userImage2Video/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userImage2Video/{_id} — Delete an image to video task
Delete a user's image to video task. Only final status tasks can be deleted (initialized/completed/failed). initialized tasks will be refunded. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserImage2VideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userImage2Video/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `400` — Bad Request - Task in processing or invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userImage2Video/prompt_extension — Extend prompt with AI
promptExtension - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImage2VideoPromptExtension`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userImage2Video/prompt_extension" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userImage2Video/flf2v_prompt_extension — Extend video prompt with AI
flf2vPromptExtension - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImage2VideoFlf2vPromptExtension`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userImage2Video/flf2v_prompt_extension" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token
#### Text to Image

##### POST /api/v1/userText2Image/start — Start text to image generation
Generate images from text prompts using AI models Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserText2ImageStart`
- JSON body fields:
  - `name` (body, optional; string; example: `My Generated Image`) — Name of the text to image task (optional, auto-generated if not provided)
  - `prompt` (body, required; string; example: `A beautiful sunset over mountains`) — Text prompt for image generation
  - `width` (body, optional; number; default: `1024`; example: `1024`) — Image width
  - `height` (body, optional; number; default: `1024`; example: `1024`) — Image height
  - `model_type` (body, optional; string; allowed: `a2e`, `seedream`; default: `a2e`; example: `a2e`) — Model type to use for generation
  - `input_images` (body, optional; string[]; max items: 10; example: `["https://example.com/image1.jpg","https://example.com/image2.jpg"]`) — Reference images for A2E/Seedream model. A2E max 2 images; Seedream 5.0 Pro max 10 images.
  - `skip_face_enhance` (body, optional; boolean; default: `false`; example: `false`) — Whether to disable face similarity enhancement for A2E image edit. Defaults to false.
  - `aspect_ratio` (body, optional; string; allowed: `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9`; example: `1:1`) — Aspect ratio for Seedream model
  - `max_images` (body, optional; number; min: 1; max: 8; example: `1`) — Maximum number of images to generate (creates multiple tasks internally)
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userText2Image/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Generated Image",
  "prompt": "A beautiful sunset over mountains",
  "width": 1024,
  "height": 1024,
  "model_type": "a2e",
  "input_images": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "skip_face_enhance": false,
  "aspect_ratio": "1:1",
  "max_images": 1,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Text to image task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userText2Image/allRecords — Get all text to image records
Retrieve paginated list of all text to image generation records for the authenticated user Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserText2ImageAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — Number of records per page
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userText2Image/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Records retrieved successfully
  - `401` — Unauthorized

##### POST /api/v1/userText2Image/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserText2ImageBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userText2Image/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userText2Image/{_id} — Get text to image record detail
Retrieve detailed information of a specific text to image generation record Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserText2ImageId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Record ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userText2Image/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Record detail retrieved successfully
  - `401` — Unauthorized
  - `404` — Record not found

##### DELETE /api/v1/userText2Image/{_id} — Delete task
Delete a specific task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserText2ImageId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userText2Image/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userText2Image/quickAddAvatar — Quick add avatar from generated image
Create a custom avatar directly from a text to image generation result Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserText2ImageQuickAddAvatar`
- JSON body fields:
  - `_id` (body, required; string; example: `507f1f77bcf86cd799439011`) — Text to image record ID
  - `gender` (body, optional; string; allowed: `female`, `male`; example: `female`) — Avatar gender
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userText2Image/quickAddAvatar" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "_id": "507f1f77bcf86cd799439011",
  "gender": "female"
}
JSON
```
- Responses:
  - `200` — Avatar created successfully
  - `400` — Bad request
  - `401` — Unauthorized
#### Nano Banana

##### POST /api/v1/userNanoBanana/start — Start Nano Banana image generation
Generate images using Nano Banana models with advanced conversational capabilities and NSFW content pre-filtering Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserNanoBananaStart`
- JSON body fields:
  - `name` (body, required; string; example: `Beautiful Landscape`) — Name of the image generation task
  - `prompt` (body, required; string; example: `A serene mountain landscape at sunset with a crystal clear lake`) — Text prompt for image generation
  - `model` (body, optional; string; allowed: `nano-banana`, `nano-banana-pro`, `nano-banana-2`, `nano-banana-2-lite`; default: `nano-banana-pro`; example: `nano-banana-pro`) — Model to use for generation. Options: nano-banana (no resolution control, auto edit mode with images), nano-banana-pro (with resolution control), nano-banana-2 (with resolution control), nano-banana-2-lite (1K only)
  - `input_images` (body, optional; string[]; example: `["https://example.com/image1.jpg"]`) — Array of input image URLs (for editing and composition modes)
  - `aspect_ratio` (body, optional; string; allowed: `auto`, `16:9`, `1:1`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`, `4:5`, `5:4`, `21:9`; default: `auto`; example: `auto`) — Aspect ratio of the generated image. Options: auto, 16:9, 1:1, 9:16, 4:3, 3:4, 2:3, 3:2, 4:5, 5:4, 21:9
  - `image_size` (body, optional; string; allowed: `1K`, `2K`, `4K`; default: `1K`; example: `1K`) — Size of the generated image. Options: 1K, 2K, 4K. Note: supported by nano-banana-pro and nano-banana-2 models; nano-banana-2-lite is always forced to 1K.
  - `google_search` (body, optional; boolean; default: `false`) — Use Google Web Search grounding to generate images based on real-time information. Only supported by nano-banana-2 model.
  - `force_generate` (body, optional; boolean; default: `true`) — Force generation even if NSFW content is detected. Defaults to true for API users, false for web users
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userNanoBanana/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "Beautiful Landscape",
  "prompt": "A serene mountain landscape at sunset with a crystal clear lake",
  "model": "nano-banana-pro",
  "input_images": [
    "https://example.com/image1.jpg"
  ],
  "aspect_ratio": "auto",
  "image_size": "1K",
  "google_search": false,
  "force_generate": true,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Nano Banana task started successfully or NSFW content detected
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userNanoBanana/allRecords — Get Nano Banana task list
Retrieve paginated list of user's Nano Banana image generation tasks Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserNanoBananaAllRecords`
- Request parameters:
  - `pageNum` (query, required; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, required; integer; min: 1; max: 100; example: `1`) — Number of items per page
  - `status` (query, optional; string; allowed: `initialized`, `processing`, `completed`, `failed`; example: `initialized`) — Filter by task status
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userNanoBanana/allRecords?pageNum=1&pageSize=1&status=initialized" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userNanoBanana/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserNanoBananaBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userNanoBanana/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userNanoBanana/detail/{id} — Get task details
Retrieve detailed information about a specific Nano Banana task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserNanoBananaDetailId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userNanoBanana/detail/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token
  - `404` — Task not found

##### DELETE /api/v1/userNanoBanana/delete/{id} — Delete task
Soft delete a Nano Banana task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserNanoBananaDeleteId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userNanoBanana/delete/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token
  - `404` — Task not found
#### GPT Image

##### POST /api/v1/userGptImage/start — Start GPT Image generation or editing
Generate images from text or edit existing images using GPT Image (4o Image) model. **Features:** - Text-to-Image generation - Image-to-Image editing (supports up to 16 reference images) - High-fidelity visuals with accurate text rendering **Output:** - Images are stored in R2 storage and expire after 3 days Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserGptImageStart`
- JSON body fields:
  - `name` (body, required; string) — Name of the image generation task
  - `prompt` (body, required; string) — Text prompt for image generation (max 3000 chars)
  - `input_images` (body, optional; string[]) — Array of input image URLs for image-to-image editing (up to 16 images for GPT Image 1.5)
  - `model` (body, optional; string; allowed: `gpt-image-1.5`, `gpt-image-2`; default: `gpt-image-1.5`) — Model variant. gpt-image-1.5 (20/35 coins) supports both aspect_ratio and quality. gpt-image-2 (25/35/45 coins per image based on resolution: 1K=25, 2K=35, 4K=45; aspect_ratio=auto is billed as 1K, aspect_ratio=1:1 + 4K is downgraded to 2K) follows the current model spec: quality is fixed to medium; aspect_ratio exposes 9 ratios (auto/1:1/9:16/21:9/16:9/4:3/3:2/3:4/2:3); resolution supports 1K/2K/4K.
  - `aspect_ratio` (body, optional; string; allowed: `auto`, `1:1`, `9:16`, `21:9`, `16:9`, `4:3`, `3:2`, `3:4`, `2:3`; default: `1:1`) — gpt-image-1.5 only supports 1:1/3:2/2:3 (other values are normalized to 1:1). gpt-image-2 supports 9 ratios. Note: 5:4/4:5 are not exposed because fallback generation would lose the aspect ratio.
  - `quality` (body, optional; string; allowed: `medium`, `high`; default: `medium`) — Image quality level. Only used by gpt-image-1.5
  - `resolution` (body, optional; string; allowed: `1K`, `2K`, `4K`; default: `1K`) — Image resolution. Only used by gpt-image-2. Constraints: aspect_ratio=1:1 cannot use 4K; aspect_ratio=auto (or omitted) only supports 1K, otherwise upstream will reject the task.
  - `force_generate` (body, optional; boolean) — Force generation even if NSFW content is detected
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userGptImage/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "<name>",
  "prompt": "<prompt>",
  "model": "gpt-image-1.5",
  "aspect_ratio": "1:1",
  "quality": "medium",
  "resolution": "1K",
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Task started successfully or NSFW content detected
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userGptImage/list — Get GPT Image task list
list - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserGptImageList`
- Request parameters:
  - `page` (query, optional; integer; default: `1`; example: `1`) — page parameter
  - `page_size` (query, optional; integer; default: `20`; example: `20`) — page_size parameter
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userGptImage/list?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userGptImage/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserGptImageBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userGptImage/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userGptImage/detail/{id} — Get task details
detail - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserGptImageDetailId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userGptImage/detail/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task detail retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userGptImage/{id} — Delete GPT Image task
delete - HTTP DELETE Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserGptImageId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userGptImage/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token
#### Flux 2

##### POST /api/v1/userFlux2/start — Start Flux 2 Pro image generation or editing
Generate high-quality images from text or edit existing images using Flux 2 Pro model. **Features:** - Text-to-Image generation with advanced prompt understanding - Image-to-Image editing (supports up to 8 reference images) - Character consistency across multiple images - Text rendering within images - High-quality output with professional-grade results **Processing Time:** - Usually 20-60 seconds **Output:** - Images are stored in R2 storage (7days-apac bucket) and expire after 7 days Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserFlux2Start`
- JSON body fields:
  - `name` (body, required; string; example: `Elon Musk and Mark Zuckerberg boxing`) — Name of the image generation task
  - `prompt` (body, required; string; example: `Elon Musk and Mark Zuckerberg boxing in a professional ring`) — Text prompt for image generation or editing instruction.
  - `input_images` (body, optional; string[]; example: `["https://example.com/reference1.jpg","https://example.com/reference2.jpg"]`) — Array of input image URLs for image-to-image editing or multi-image composition (up to 8 images). When provided, automatically switches to image-to-image mode for character consistency.
  - `aspect_ratio` (body, optional; string; allowed: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`, `custom`, `match_input_image`; default: `9:16`; example: `9:16`) — Aspect ratio of the generated image. Options: 1:1, 16:9, 9:16, 4:3, 3:4, 2:3, 3:2, custom, match_input_image
  - `resolution` (body, optional; string; allowed: `1K`, `2K`; default: `1K`; example: `1K`) — Resolution of the generated image. - 1K: ~1 megapixel - 2K: ~2 megapixels
  - `force_generate` (body, optional; boolean; default: `true`) — Force generation even if NSFW content is detected. Defaults to true for API users, false for web users
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userFlux2/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "Elon Musk and Mark Zuckerberg boxing",
  "prompt": "Elon Musk and Mark Zuckerberg boxing in a professional ring",
  "input_images": [
    "https://example.com/reference1.jpg",
    "https://example.com/reference2.jpg"
  ],
  "aspect_ratio": "9:16",
  "resolution": "1K",
  "force_generate": true,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Flux 2 Pro task started successfully or NSFW content detected
  - `400` — Invalid request parameters
  - `401` — Unauthorized - Invalid or missing token
  - `402` — Insufficient credits
  - `500` — Internal server error

##### GET /api/v1/userFlux2/list — Get Flux 2 Pro task list
Retrieve paginated list of user's Flux 2 Pro image generation tasks. Tasks are sorted by creation date (newest first). Only returns tasks that haven't expired (7 days retention). Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFlux2List`
- Request parameters:
  - `page` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number (starting from 1)
  - `page_size` (query, optional; integer; default: `20`; min: 1; max: 100; example: `20`) — Number of items per page (max 100)
  - `status` (query, optional; string; allowed: `initialized`, `processing`, `completed`, `failed`; example: `initialized`) — Filter by task status
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userFlux2/list?page=1&page_size=20&status=initialized" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userFlux2/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserFlux2BatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userFlux2/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userFlux2/detail/{id} — Get task details
Retrieve detailed information about a specific Flux 2 Pro task, including generation status, image URL, and processing time Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFlux2DetailId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userFlux2/detail/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task detail retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token
  - `404` — Task not found

##### DELETE /api/v1/userFlux2/{id} — Delete Flux 2 Pro task
Soft delete a Flux 2 Pro task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserFlux2Id`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userFlux2/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token
#### Qwen Image

##### POST /api/v1/userQwen2Image/start — Start a new Qwen2 image generation/edit task
start - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserQwen2ImageStart`
- JSON body fields:
  - `name` (body, required; string) — Task name
  - `prompt` (body, required; string) — Image generation or editing prompt
  - `model` (body, optional; string; allowed: `qwen-image-2.0`, `qwen-image-2.0-pro`; default: `qwen-image-2.0`)
  - `input_images` (body, optional; string[]) — Optional public reference image URLs
  - `size` (body, optional; string; allowed: `1024*1024`, `1328*880`, `880*1328`, `1152*864`, `864*1152`, `1280*720`, `720*1280`, `1512*648`; default: `1024*1024`)
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userQwen2Image/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "<name>",
  "prompt": "<prompt>",
  "model": "qwen-image-2.0",
  "size": "1024*1024",
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Task created successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userQwen2Image/list — List Qwen2 image tasks
list - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserQwen2ImageList`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userQwen2Image/list" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userQwen2Image/detail/{id} — Get Qwen2 image task details
detail - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserQwen2ImageDetailId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userQwen2Image/detail/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userQwen2Image/batchDetail — Batch get Qwen2 image task details
batchDetail - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserQwen2ImageBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userQwen2Image/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Task details
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userQwen2Image/{id} — Delete a Qwen2 image task
delete - HTTP DELETE Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserQwen2ImageId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userQwen2Image/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted
  - `401` — Unauthorized - Invalid or missing JWT token
#### Kling Image

##### POST /api/v1/userKlingImage/start — Start Kling 3.0 image generation
start - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserKlingImageStart`
- JSON body fields:
  - `name` (body, required; string) — Task name
  - `prompt` (body, required; string) — Image generation prompt
  - `input_images` (body, optional; string[]) — Optional public reference image URLs
  - `aspect_ratio` (body, optional; string; allowed: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`, `21:9`; default: `9:16`)
  - `resolution` (body, optional; string; allowed: `1k`, `2k`; default: `1k`)
  - `n` (body, optional; integer; min: 1; max: 9)
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userKlingImage/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "<name>",
  "prompt": "<prompt>",
  "aspect_ratio": "9:16",
  "resolution": "1k",
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Task created successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userKlingImage/list — List Kling image tasks
list - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserKlingImageList`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userKlingImage/list" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userKlingImage/batchDetail — Batch get Kling image task details
batchDetail - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserKlingImageBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userKlingImage/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Task details
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userKlingImage/detail/{id} — Get Kling image task details
detail - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserKlingImageDetailId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userKlingImage/detail/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userKlingImage/{id} — Delete a Kling image task
delete - HTTP DELETE Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserKlingImageId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — id parameter
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userKlingImage/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted
  - `401` — Unauthorized - Invalid or missing JWT token
#### Wan Image to Video

##### POST /api/v1/userWan25/start — Start Wan video generation
Start a Wan video generation task. This endpoint supports Wan 2.5 image-to-video, Wan 2.6 image-to-video and Wan 2.7 multi-mode video generation. For Wan 2.7, set `model` to `wan2.7-i2v` and select the generation mode with `task_type`: - `text_to_video`: text prompt only. Do not provide image/video material. - `first_frame`: image-to-video from one first-frame image. Requires `image_url`. - `first_last_frame`: image-to-video with first and last frame control. Requires `image_url` and `last_frame_url`. - `reference_image`: reference-image-to-video. Requires `reference_image_urls` with 1 to 5 image URLs. - `video_extend`: extend an existing video clip. Requires `first_clip_url`; optional `last_frame_url`. - `video_edit`: edit an existing video. Requires `edit_video_url`; optional `reference_image_urls` with up to 3 image URLs. `text_to_video`, `first_last_frame`, `reference_image`, `video_extend` and `video_edit` are only available when `model=wan2.7-i2v`. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWan25Start`
- JSON body fields:
  - `name` (body, optional; string; example: `My Wan Video`) — Optional display name for the task
  - `image_url` (body, optional; string; example: `https://example.com/image.jpg`) — Source image URL. Required for `first_frame` and `first_last_frame`.
  - `prompt` (body, required; string; example: `Make the person in the image wave their hand`) — Generation prompt
  - `negative_prompt` (body, optional; string; example: `blurry, distorted`) — Negative prompt to avoid unwanted features
  - `duration` (body, optional; string; allowed: `5`, `6`, `7`, `8`, `9`, `10`, `15`; default: `5`) — Video duration in seconds. Options depend on task_type: text_to_video/first_frame/first_last_frame/reference_image/video_extend use 5/10/15; video_edit uses 5/6/7/8/9/10. Wan 2.5 only supports 5/10.
  - `resolution` (body, optional; string; allowed: `480p`, `720p`, `1080p`; default: `720p`) — Video resolution
  - `ratio` (body, optional; string; allowed: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`; default: `16:9`) — Video aspect ratio. Only used by Wan 2.7 `text_to_video` and `reference_image`.
  - `enable_prompt_expansion` (body, optional; boolean; default: `false`) — Whether to enable prompt rewriting using LLM
  - `multi_shots` (body, optional; boolean; default: `false`) — Enable intelligent multi-shot segmentation (only active when enable_prompt_expansion is true)
  - `model` (body, optional; string; allowed: `wan2.5-i2v-preview`, `wan2.6-i2v`, `wan2.6-i2v-flash`, `wan2.7-i2v`; default: `wan2.5-i2v-preview`) — AI model version (wan2.6-i2v and wan2.7-i2v require VIP/Max user, wan2.6-i2v-flash is available to all users)
  - `task_type` (body, optional; string; allowed: `text_to_video`, `first_frame`, `first_last_frame`, `reference_image`, `video_extend`, `video_edit`; default: `first_frame`) — Wan 2.7 generation mode. Only used when `model=wan2.7-i2v`.
  - `last_frame_url` (body, optional; string; example: `https://example.com/last-frame.jpg`) — Last-frame image URL. Required for `first_last_frame`; optional for `video_extend`.
  - `first_clip_url` (body, optional; string; example: `https://example.com/clip.mp4`) — Existing video clip URL. Required for Wan 2.7 `video_extend`.
  - `edit_video_url` (body, optional; string; example: `https://example.com/input-video.mp4`) — Input video URL. Required for Wan 2.7 `video_edit`.
  - `reference_image_urls` (body, optional; string[]; example: `["https://example.com/reference-1.jpg","https://example.com/reference-2.jpg"]`) — Reference image URLs. Required for Wan 2.7 `reference_image` (1-5 images); optional for `video_edit` (up to 3 images).
  - `seed` (body, optional; number; min: 0; max: 2147483647) — Random seed for reproducibility. Value must be in the range [0, 2147483647]. If not specified, system generates a random seed.
  - `audio` (body, optional; boolean; default: `true`) — Whether to generate audio for the video
  - `audio_url` (body, optional; string; example: `https://example.com/audio.mp3`) — URL of audio file to use for first-frame/first-last-frame video generation. Supports WAV/MP3, 3-30s duration, max 15MB. If longer than video duration, audio will be truncated.
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userWan25/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Wan Video",
  "image_url": "https://example.com/image.jpg",
  "prompt": "Make the person in the image wave their hand",
  "negative_prompt": "blurry, distorted",
  "duration": "5",
  "resolution": "720p",
  "ratio": "16:9",
  "enable_prompt_expansion": false,
  "multi_shots": false,
  "model": "wan2.5-i2v-preview",
  "task_type": "first_frame",
  "last_frame_url": "https://example.com/last-frame.jpg",
  "first_clip_url": "https://example.com/clip.mp4",
  "edit_video_url": "https://example.com/input-video.mp4",
  "reference_image_urls": [
    "https://example.com/reference-1.jpg",
    "https://example.com/reference-2.jpg"
  ],
  "audio": true,
  "audio_url": "https://example.com/audio.mp3",
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Wan video task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userWan25/allRecords — Get all Wan 2.5 tasks
Get paginated list of user's Wan 2.5 tasks Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWan25AllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — Number of items per page
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userWan25/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userWan25/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWan25BatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userWan25/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userWan25/{_id} — Get Wan 2.5 task details
Get detailed information about a specific Wan 2.5 task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWan25Id`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userWan25/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userWan25/{_id} — Delete a Wan 2.5 task
Delete a user's Wan 2.5 image to video task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserWan25Id`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userWan25/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userWanSpicy/start — Start Wan Spicy image-to-video generation
Start a Wan Spicy image-to-video task via mulerouter.ai/carrothub. - wan2.7-i2v-spicy: with audio support, resolution 720p/1080p, duration 2-15 seconds. - wan2.2-i2v-spicy: no audio, resolution 480p/720p, duration 5 or 8 seconds. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWanSpicyStart`
- JSON body fields:
  - `model` (body, required; string; allowed: `wan2.7-i2v-spicy`, `wan2.2-i2v-spicy`; default: `wan2.7-i2v-spicy`) — Model variant (2.7 supports audio, 2.2 no audio)
  - `name` (body, optional; string) — Optional display name for the task
  - `prompt` (body, required; string) — Generation prompt
  - `negative_prompt` (body, optional; string) — Negative prompt (only valid when model = wan2.7-i2v-spicy)
  - `image_url` (body, required; string) — Reference image URL (https only)
  - `audio_url` (body, optional; string) — Audio URL (https, .wav/.mp3, only valid when model = wan2.7-i2v-spicy)
  - `resolution` (body, required; string; allowed: `480p`, `720p`, `1080p`) — Resolution tier (wan2.7 720p/1080p, wan2.2 480p/720p)
  - `duration` (body, required; number) — Output duration in seconds (wan2.7 2-15, wan2.2 5 or 8)
  - `prompt_extend` (body, optional; boolean; default: `true`)
  - `seed` (body, optional; integer) — Random seed
  - `minor_suspected_skip` (body, optional; boolean; default: `false`) — Skip pre-charge minor-suspect prompt for the input image
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userWanSpicy/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "model": "wan2.7-i2v-spicy",
  "prompt": "Animate the subject with smooth, cinematic motion.",
  "image_url": "https://example.com/input.jpg",
  "resolution": "720p",
  "duration": 5
}
JSON
```
- Responses:
  - `200` — Task started successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userWanSpicy/allRecords — Get all Wan Spicy tasks
allRecords - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWanSpicyAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — pageNum parameter
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — pageSize parameter
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userWanSpicy/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userWanSpicy/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserWanSpicyBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userWanSpicy/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userWanSpicy/{_id} — Get Wan Spicy task details
detail - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserWanSpicyId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userWanSpicy/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userWanSpicy/{_id} — Delete a Wan Spicy task
delete - HTTP DELETE Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserWanSpicyId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userWanSpicy/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token
#### HappyHorse Video

##### POST /api/v1/userHappyhorseVideo/start — Start HappyHorse video generation task (T2V / I2V / R2V / Video-Edit)
Generate a video using HappyHorse models on Alibaba DashScope. If model_version is omitted, new tasks keep the legacy 1.0 behavior. Supported modes: - t2v: text → video (happyhorse-1.0-t2v / happyhorse-1.1-t2v) - i2v: image first_frame → video (happyhorse-1.0-i2v / happyhorse-1.1-i2v) - r2v: reference images → video (happyhorse-1.0-r2v / happyhorse-1.1-r2v) - video-edit: video + reference images → edited video (happyhorse-1.0-video-edit) Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserHappyhorseVideoStart`
- JSON body fields:
  - `mode` (body, required; string; allowed: `t2v`, `i2v`, `r2v`, `video-edit`) — Generation mode
  - `name` (body, optional; string) — Task name
  - `model_version` (body, optional; string; allowed: `1.0`, `1.1`; default: `1.0`) — Model version for t2v / i2v / r2v. video-edit always uses 1.0. HappyHorse 1.0 keeps the legacy duration/ratio options; 1.1 supports 3-15s and additional aspect ratios.
  - `prompt` (body, optional; string) — Required for t2v / r2v / video-edit; optional for i2v
  - `image_url` (body, optional; string) — First frame image URL (i2v only)
  - `reference_image_urls` (body, optional; string[]) — Reference images (r2v requires 1-9; video-edit allows 0-5)
  - `edit_video_url` (body, optional; string) — Input video URL (video-edit only)
  - `input_video_seconds` (body, optional; number) — Frontend-detected input video duration in seconds (used to estimate coins for video-edit)
  - `duration` (body, optional; string; allowed: `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`; default: `5`) — Output duration (seconds). model_version=1.0 supports 5/10/15; model_version=1.1 supports 3-15. Ignored for video-edit (decided by input video).
  - `resolution` (body, optional; string; allowed: `720P`, `1080P`; default: `720P`)
  - `ratio` (body, optional; string; allowed: `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `4:5`, `5:4`, `9:21`, `21:9`; default: `16:9`) — Aspect ratio (t2v / r2v only). model_version=1.0 supports 16:9, 9:16, 1:1, 4:3, 3:4; model_version=1.1 also supports 4:5, 5:4, 9:21, 21:9.
  - `audio_setting` (body, optional; string; allowed: `auto`, `origin`; default: `auto`) — Audio control (video-edit only). auto = model decides; origin = keep input video audio.
  - `seed` (body, optional; integer) — Random seed [0, 2147483647]
  - `watermark` (body, optional; boolean; default: `true`) — DashScope watermark switch
  - `minor_suspected_skip` (body, optional; boolean; default: `false`)
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userHappyhorseVideo/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "mode": "t2v",
  "model_version": "1.0",
  "duration": "5",
  "resolution": "720P",
  "ratio": "16:9",
  "audio_setting": "auto",
  "watermark": true,
  "minor_suspected_skip": false,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Task created successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userHappyhorseVideo/allRecords — List HappyHorse tasks
allRecords - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserHappyhorseVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — pageNum parameter
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — pageSize parameter
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userHappyhorseVideo/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userHappyhorseVideo/batchDetail — Batch query task details
batchDetail - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserHappyhorseVideoBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`)
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userHappyhorseVideo/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userHappyhorseVideo/{_id} — Get HappyHorse task details
detail - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserHappyhorseVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userHappyhorseVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task detail
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userHappyhorseVideo/{_id} — Delete a HappyHorse task
delete - HTTP DELETE Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserHappyhorseVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userHappyhorseVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted
  - `401` — Unauthorized - Invalid or missing JWT token
#### Seedance 1.5 Pro

##### POST /api/v1/seedanceVideo/start — Start Seedance 1.5 Pro video generation
Generate videos using BytePlus ModelArk Seedance 1.5 Pro. Supports 3 modes - text-to-video, image-to-video, first-last-frames. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1SeedanceVideoStart`
- JSON body fields:
  - `name` (body, optional; string; example: `My Seedance Video`) — Name of the video generation task
  - `mode` (body, optional; string; allowed: `text-to-video`, `image-to-video`; default: `text-to-video`; example: `image-to-video`) — Generation mode. For first-last-frames usage, send mode=image-to-video together with image_url + end_image_url; the backend will normalize it.
  - `prompt` (body, required; string; example: `A girl holding a fox, the girl opens her eyes...`) — Text prompt describing the desired video
  - `image_url` (body, optional; string; example: `https://example.com/input.jpg`) — Input image URL (required for image-to-video mode; also used as the first frame in first-last-frames usage)
  - `end_image_url` (body, optional; string; example: `https://example.com/last.jpg`) — Last frame image URL. When provided together with image_url, mode is automatically treated as first-last-frames.
  - `duration` (body, optional; string; allowed: `5`, `10`; default: `5`) — Video duration in seconds
  - `aspect_ratio` (body, optional; string; allowed: `16:9`, `9:16`, `1:1`; default: `16:9`) — Video aspect ratio
  - `resolution` (body, optional; string; allowed: `480p`, `720p`; default: `720p`) — Video resolution
  - `camera_fixed` (body, optional; boolean; default: `false`) — Whether the camera is fixed
  - `generate_audio` (body, optional; boolean; default: `false`) — Whether to generate audio
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/seedanceVideo/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Seedance Video",
  "mode": "image-to-video",
  "prompt": "A girl holding a fox, the girl opens her eyes...",
  "image_url": "https://example.com/input.jpg",
  "end_image_url": "https://example.com/last.jpg",
  "duration": "5",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "camera_fixed": false,
  "generate_audio": false,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Video generation task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/seedanceVideo/allRecords — Get all Seedance video records
Retrieve all Seedance video generation records for the authenticated user Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1SeedanceVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `20`; example: `20`) — Items per page
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/seedanceVideo/allRecords?pageNum=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successfully retrieved records
  - `401` — Unauthorized - Invalid or missing JWT token
#### Seedance 2.0

##### POST /api/v1/seedance2Video/start — Start Seedance 2.0 video generation
Generate videos with Seedance 2.0 (standard/mini/fast). Supports text-to-video, image-to-video, first-last-frames, and reference modes. Image / video / audio inputs must be public URLs (asset:// URIs are not accepted from clients). Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1Seedance2VideoStart`
- JSON body fields:
  - `name` (body, optional; string)
  - `mode` (body, optional; string; allowed: `text-to-video`, `image-to-video`, `first-last-frames`, `reference`; default: `text-to-video`) — image-to-video uses image_url (+ optional last_frame_url); first-last-frames uses first_frame_url + last_frame_url; reference accepts any combination of reference_urls (image) / video_urls / audio_urls — audio cannot be used alone, must accompany at least one image or video reference.
  - `model_version` (body, optional; string; allowed: `standard`, `mini`, `fast`; default: `standard`)
  - `prompt` (body, required; string)
  - `image_url` (body, optional; string) — First frame for image-to-video mode.
  - `first_frame_url` (body, optional; string) — Required for first-last-frames mode.
  - `last_frame_url` (body, optional; string) — Optional last frame for image-to-video; required for first-last-frames.
  - `reference_urls` (body, optional; string[]; max items: 9) — Reference images for reference mode (1-9 images).
  - `video_urls` (body, optional; string[]; max items: 3) — Reference videos (max 3, each 2-15s, total <= 15 × number_of_videos seconds, mp4/mov). Recommended to also pass input_video_duration for accurate billing; if omitted, the server will ffprobe each URL (https only, public hosts) with a 10s per-URL timeout to derive total seconds.
  - `audio_urls` (body, optional; string[]; max items: 3) — Reference audios (max 3, each 2-15s, total <=15s, mp3/wav). Audio cannot be used standalone; at least one image or video reference is required.
  - `input_video_duration` (body, optional; number; min: 2; max: 45) — Total duration in seconds of all reference videos (sum of each clip's length). Recommended whenever video_urls is non-empty — billing uses (input + output) × video rate. If omitted or invalid the server probes the URLs via ffprobe to fill it in. Must be within [2, 15 × number_of_videos].
  - `duration` (body, optional; integer; default: `5`; min: 4; max: 15)
  - `aspect_ratio` (body, optional; string; allowed: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`; default: `16:9`)
  - `resolution` (body, optional; string; allowed: `480p`, `720p`, `1080p`, `4k`; default: `720p`) — 1080p and 4k are only supported by standard model_version
  - `generate_audio` (body, optional; boolean; default: `true`) — Defaults to true to match billing (audio is included); pass false explicitly to disable.
  - `minor_suspected_skip` (body, optional; boolean; default: `false`) — Skip soft minor-suspect block (code 1004); hard CSAM block (code 1003) is always enforced.
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/seedance2Video/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "mode": "text-to-video",
  "model_version": "standard",
  "prompt": "<prompt>",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "generate_audio": true,
  "minor_suspected_skip": false,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Task started successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/seedance2Video/allRecords — Get all records
List the current user's Seedance 2.0 video tasks with pagination. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1Seedance2VideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number (1-based)
  - `pageSize` (query, optional; integer; default: `20`; example: `20`) — Page size
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/seedance2Video/allRecords?pageNum=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Success
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/seedance2Video/batchDetail — Batch get task details
Fetch multiple Seedance 2.0 video task records in a single request (up to 200 ids). Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1Seedance2VideoBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Task record ids (max 200)
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/seedance2Video/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Success
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/seedance2Video/{_id} — Get task detail
Get detail of a Seedance 2.0 video task by id. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1Seedance2VideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task record id
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/seedance2Video/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Success
  - `401` — Unauthorized - Invalid or missing JWT token

##### PUT /api/v1/seedance2Video/{_id} — Rename task
Rename an existing Seedance 2.0 video task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `putApiV1Seedance2VideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task record id
- JSON body fields:
  - `name` (body, required; string; example: `My Task`) — New task name
- Example request:
```bash
curl -X PUT "https://cheap.dev/api/v1/seedance2Video/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Task"
}
JSON
```
- Responses:
  - `200` — Updated
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/seedance2Video/{_id} — Delete task
Delete a Seedance 2.0 video task by id. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1Seedance2VideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task record id
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/seedance2Video/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Deleted
  - `401` — Unauthorized - Invalid or missing JWT token
#### Veo Video

##### POST /api/v1/veoVideo/start — Start Veo 3.1 video generation
Generate videos using Google DeepMind's Veo 3.1 AI model. Supports text-to-video, image-to-video, and reference-based generation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1VeoVideoStart`
- JSON body fields:
  - `name` (body, optional; string; example: `My Veo Video`) — Name of the video generation task (optional, auto-generated if not provided)
  - `prompt` (body, required; string; example: `Two person street interview in New York City. Sample Dialogue: Host: "Did you hear the news?" Person: "Yes! Veo 3.1 is now available on A2E. If you want to see it, go check their website."`) — Text prompt describing the video content. Can be empty to use default placeholder text.
  - `generationType` (body, optional; string; allowed: `TEXT_2_VIDEO`, `FIRST_AND_LAST_FRAMES_2_VIDEO`, `REFERENCE_2_VIDEO`; default: `TEXT_2_VIDEO`; example: `TEXT_2_VIDEO`) — Type of generation (TEXT_2_VIDEO for text-only, FIRST_AND_LAST_FRAMES_2_VIDEO for image frames, REFERENCE_2_VIDEO for reference images)
  - `imageUrls` (body, optional; string[]; example: `["https://example.com/start_frame.jpg","https://example.com/end_frame.jpg"]`) — Image URLs for image-to-video generation. For FIRST_AND_LAST_FRAMES_2_VIDEO mode, 1-2 images (start/end frames). For REFERENCE_2_VIDEO mode, 1-3 reference images.
  - `model` (body, optional; string; allowed: `veo3`, `veo3_fast`; default: `veo3_fast`; example: `veo3_fast`) — Generation model (veo3 for quality, veo3_fast for speed)
  - `aspectRatio` (body, optional; string; allowed: `16:9`, `9:16`, `Auto`; default: `Auto`; example: `16:9`) — Video aspect ratio (Auto will determine automatically)
  - `watermark` (body, optional; string; example: `MyBrand`) — Custom watermark text (optional)
  - `seeds` (body, optional; number; example: `12345`) — Random seed for reproducible generation (10000-99999, optional)
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/veoVideo/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Veo Video",
  "prompt": "Two person street interview in New York City. Sample Dialogue: Host: \"Did you hear the news?\" Person: \"Yes! Veo 3.1 is now available on A2E. If you want to see it, go check their website.\"",
  "generationType": "TEXT_2_VIDEO",
  "imageUrls": [
    "https://example.com/start_frame.jpg",
    "https://example.com/end_frame.jpg"
  ],
  "model": "veo3_fast",
  "aspectRatio": "16:9",
  "watermark": "MyBrand",
  "seeds": 12345,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Video generation task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/veoVideo/allRecords — Get all Veo video records
Retrieve paginated list of user's Veo video generation records Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1VeoVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — Number of records per page
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/veoVideo/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Records retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/veoVideo/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1VeoVideoBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/veoVideo/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/veoVideo/{_id} — Get Veo video detail
Retrieve detailed information of a specific Veo video generation record Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1VeoVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Video record ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/veoVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Video detail retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/veoVideo/{_id} — Delete Veo video record
Soft delete a Veo video generation record Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1VeoVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Video record ID
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/veoVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Video record deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/veoVideo/{_id}/1080p — Get 1080P HD video
Retrieve 1080P high-definition version of the video (only available for 16:9 aspect ratio) Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1VeoVideoId1080p`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Video record ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/veoVideo/507f1f77bcf86cd799439011/1080p" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — 1080P video retrieved successfully
  - `202` — 1080P video is being processed, please try again later
  - `400` — Invalid aspect ratio or missing task ID
  - `401` — Unauthorized - Invalid or missing JWT token
#### Grok Video

##### POST /api/v1/grokVideo/start — Start Grok Imagine video generation
Generate videos using Grok Imagine. Supports both text-to-video and image-to-video modes. **Modes:** - `text-to-video`: Generate video from a text prompt. Requires `prompt`. - `image-to-video`: Generate video from a reference image. Requires at least one image in `image_urls` (or `image_url`). **Duration:** `6`, `10`, or `15` seconds. **Model version:** `legacy` (default) uses the existing Grok Imagine path. `1.5` uses Grok Imagine Video 1.5 and only supports `image-to-video`. **Mode:** `fun`, `normal` (default), or `spicy`. This is an asynchronous API. After calling this endpoint, poll `/api/v1/grokVideo/{_id}` to check task status until `current_status` becomes `completed` or `failed`. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1GrokVideoStart`
- JSON body fields:
  - `name` (body, optional; string; example: `My Grok Video`) — Name of the video generation task (optional, for identifying the task)
  - `model_type` (body, optional; string; allowed: `text-to-video`, `image-to-video`; default: `text-to-video`; example: `text-to-video`) — Generation mode. `text-to-video` generates video from text prompt, `image-to-video` generates video from a reference image.
  - `model_version` (body, optional; string; allowed: `legacy`, `1.5`; default: `legacy`; example: `1.5`) — Model version. `1.5` uses Grok Imagine Video 1.5 and only supports image-to-video.
  - `prompt` (body, optional; string; example: `A cat playing with a ball of yarn in a cozy living room, warm lighting, cinematic style`) — Text prompt describing the video content. Required for text-to-video mode, optional for image-to-video mode.
  - `mode` (body, optional; string; allowed: `fun`, `normal`, `spicy`; default: `normal`; example: `normal`) — Generation style mode. For image-to-video, upstream may fallback spicy to normal.
  - `image_urls` (body, optional; string[]; example: `["https://example.com/reference.jpg"]`) — Array of reference image URLs for image-to-video mode. At least one image is required when `model_type` is `image-to-video`.
  - `image_url` (body, optional; string; example: `https://example.com/image.jpg`) — Single reference image URL (alternative to `image_urls`). Will be prepended to `image_urls` array.
  - `aspect_ratio` (body, optional; string; allowed: `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`; default: `16:9`; example: `16:9`) — Video aspect ratio. Legacy text-to-video supports 1:1/16:9/9:16; legacy image-to-video can additionally accept 4:3/3:4/3:2/2:3 depending on the selected generation path. Grok 1.5 accepts the full list including auto.
  - `duration` (body, optional; string; allowed: `6`, `10`, `15`; default: `6`; example: `6`) — Video duration in seconds.
  - `nsfw_checker` (body, optional; boolean; default: `false`) — Whether to enable additional NSFW checking for Grok 1.5.
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/grokVideo/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Grok Video",
  "model_type": "image-to-video",
  "model_version": "1.5",
  "prompt": "Bring the reference image to life with subtle, natural motion.",
  "image_url": "https://example.com/reference.jpg",
  "aspect_ratio": "16:9",
  "duration": "6"
}
JSON
```
- Responses:
  - `200` — Video generation task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/grokVideo/allRecords — Get Grok Video task list
Retrieve paginated list of user's Grok Imagine video generation tasks, ordered by creation time (newest first). Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1GrokVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number (starts from 1)
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — Number of items per page
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/grokVideo/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
  - `401` — Unauthorized

##### POST /api/v1/grokVideo/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1GrokVideoBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/grokVideo/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/grokVideo/{_id} — Get Grok Video task detail
Retrieve detailed information of a specific Grok Imagine video generation task by ID. Use this endpoint to poll task status after creation. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1GrokVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID (MongoDB ObjectId)
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/grokVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task detail retrieved successfully
  - `401` — Unauthorized

##### DELETE /api/v1/grokVideo/{_id} — Delete Grok Video task
Delete a specific Grok Imagine video generation task by ID. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1GrokVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID (MongoDB ObjectId)
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/grokVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `401` — Unauthorized
#### Kling Video

##### POST /api/v1/klingVideo/start — Start Kling video generation
Generate videos using Kling Official API. **Modes:** - `text-to-video` – generate video from text prompt - `image-to-video` – generate video from an image (+ optional end frame in PRO) - `motion-control` – transfer motion from a video onto an image **Versions:** `2.6` (5s/10s) and `3.0` (standard/fast: 3s–15s) **Quality:** `std` (Standard), `pro` (Professional), or `4k` (Kling 3.0 Native 4K for text/image video). Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1KlingVideoStart`
- JSON body fields:
  - `name` (body, optional; string; example: `My Kling Video`) — Name of the video generation task
  - `mode` (body, required; string; allowed: `text-to-video`, `image-to-video`, `motion-control`; example: `image-to-video`) — Generation mode: text-to-video, image-to-video, or motion-control
  - `prompt` (body, required; string; example: `A beautiful sunset over the ocean`) — Text prompt describing the desired video
  - `version` (body, optional; string; allowed: `2.6`, `3.0`; default: `2.6`; example: `3.0`) — Kling model version. 2.6 supports 5s/10s, 3.0 supports 5s/10s/15s
  - `model_version` (body, optional; string; allowed: `standard`, `fast`; default: `standard`; example: `fast`) — Kling 3.0 model variant. fast requires version=3.0, supports text-to-video/image-to-video, supports 3–15s, and uses resolution instead of quality_mode=4k.
  - `resolution` (body, optional; string; allowed: `720p`, `1080p`; default: `720p`; example: `720p`) — Output resolution for model_version=fast
  - `quality_mode` (body, optional; string; allowed: `std`, `pro`, `4k`; default: `std`; example: `std`) — Quality mode. 4K is only available for Kling 3.0 text-to-video and image-to-video
  - `duration` (body, optional; string; allowed: `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `15`; default: `5`; example: `5`) — Video duration in seconds. Kling 2.6 supports 5s/10s; Kling 3.0 supports 3–15s.
  - `image_url` (body, optional; string; example: `https://example.com/input.jpg`) — Input image URL (required for image-to-video and motion-control modes)
  - `video_url` (body, optional; string; example: `https://example.com/input.mp4`) — Input video URL (required for motion-control mode)
  - `aspect_ratio` (body, optional; string; allowed: `16:9`, `9:16`, `1:1`; default: `16:9`; example: `16:9`) — Video aspect ratio (text-to-video mode only)
  - `sound` (body, optional; boolean; default: `false`; example: `false`) — Enable audio generation. For v2.6 only available in PRO mode (STD does not support sound). v3.0 supports sound in STD/PRO. 4K is billed as a separate quality tier.
  - `end_image_url` (body, optional; string; example: `https://example.com/end_frame.jpg`) — End frame image URL (image-to-video + PRO mode only). Cannot be used with sound in v2.6
  - `character_orientation` (body, optional; string; allowed: `video`, `image`; default: `video`; example: `video`) — Character orientation for motion-control mode. 'image' limits duration to 3-10s, 'video' allows 3-30s
  - `negative_prompt` (body, optional; string; example: `blurry, low quality`) — Negative prompt to avoid certain elements
  - `seed` (body, optional; number; example: `12345`) — Random seed for reproducibility
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/klingVideo/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Kling Video",
  "mode": "image-to-video",
  "prompt": "A beautiful sunset over the ocean",
  "version": "3.0",
  "model_version": "fast",
  "resolution": "720p",
  "quality_mode": "std",
  "duration": "5",
  "image_url": "https://example.com/input.jpg",
  "video_url": "https://example.com/input.mp4",
  "aspect_ratio": "16:9",
  "sound": false,
  "end_image_url": "https://example.com/end_frame.jpg",
  "character_orientation": "video",
  "negative_prompt": "blurry, low quality",
  "seed": 12345,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Video generation task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/klingVideo/allRecords — Get all Kling video records
Retrieve all Kling video generation records for the authenticated user Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1KlingVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `20`; example: `20`) — Items per page
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/klingVideo/allRecords?pageNum=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successfully retrieved records
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/klingVideo/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1KlingVideoBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/klingVideo/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/klingVideo/{_id} — Get Kling video detail
Get detailed information about a specific Kling video generation task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1KlingVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/klingVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successfully retrieved task details
  - `401` — Unauthorized - Invalid or missing JWT token
  - `404` — Task not found

##### PUT /api/v1/klingVideo/{_id} — Update Kling video name
Update the name of a Kling video generation task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `putApiV1KlingVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- JSON body fields:
  - `name` (body, required; string; example: `My Task`) — New name for the task
- Example request:
```bash
curl -X PUT "https://cheap.dev/api/v1/klingVideo/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Task"
}
JSON
```
- Responses:
  - `200` — Name updated successfully
  - `401` — Unauthorized - Invalid or missing JWT token
  - `404` — Task not found

##### DELETE /api/v1/klingVideo/{_id} — Delete Kling video
Delete a Kling video generation task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1KlingVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/klingVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token
  - `404` — Task not found
#### Kling Omni

##### POST /api/v1/klingOmni/start — Start Kling Omni video generation
Generate videos using Kling Omni API (model: kling-v3-omni). This is a simplified wrapper around the official Kling API. **Key Features:** - Multi-reference images: up to 7 images, use `<<<image_N>>>` tags in prompt - Multi-shot editing: AI Director (intelligence) or manual (customize) storyboard - Native sound generation via `sound` parameter - Flexible duration: 3–15 seconds **Simplified vs Official API:** - `image_list`: accepts `string[]` (image URLs); official uses `[{image_url, type?}]`, auto-converted on server - `sound`: accepts `boolean`; official uses `"on"/"off"`, auto-converted on server - `multi_prompt`: items need `prompt` + `duration`; server auto-adds `index` field for official API - `prompt` is required when `multi_shot=false` or `shot_type=intelligence` - `multi_prompt` total duration must equal `duration` when `shot_type=customize` Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1KlingOmniStart`
- JSON body fields:
  - `name` (body, optional; string; example: `My Kling Omni Video`) — Task name (internal use)
  - `prompt` (body, required; string; example: `<<<image_1>>> walks towards <<<image_2>>> in a sunny park`) — Text prompt. Use <<<image_N>>> to reference images. Required when multi_shot=false or shot_type=intelligence.
  - `image_list` (body, optional; string[]; example: `["https://example.com/ref1.jpg"]`) — Reference image URLs (up to 7, jpg/jpeg/png, max 10MB). Simplified: pass URLs directly; server converts to official [{image_url}] format.
  - `mode` (body, optional; string; allowed: `std`, `pro`; default: `std`) — Video generation mode. std=standard (720p), pro=professional (1080p)
  - `duration` (body, required; string; default: `5`) — Video duration in seconds (3–15)
  - `aspect_ratio` (body, optional; string; allowed: `16:9`, `9:16`, `1:1`; default: `16:9`)
  - `sound` (body, optional; boolean; default: `false`) — Enable native sound generation. Simplified: pass boolean; server converts to official 'on'/'off'.
  - `multi_shot` (body, optional; boolean; default: `false`) — Enable multi-shot mode
  - `shot_type` (body, optional; string; allowed: `intelligence`, `customize`) — Shot type. Required when multi_shot=true.
  - `multi_prompt` (body, optional; object[]) — Manual storyboard (required when shot_type=customize, 1–6 items, total duration must equal duration). Server auto-adds index field for official API.
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/klingOmni/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Kling Omni Video",
  "prompt": "<<<image_1>>> walks towards <<<image_2>>> in a sunny park",
  "image_list": [
    "https://example.com/ref1.jpg"
  ],
  "mode": "std",
  "duration": "5",
  "aspect_ratio": "16:9",
  "sound": false,
  "multi_shot": false,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Video generation task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/klingOmni/allRecords — Get all Kling Omni video records
Retrieve paginated list of Kling Omni video generation tasks for the authenticated user. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1KlingOmniAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `20`; example: `20`) — Number of records per page
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/klingOmni/allRecords?pageNum=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Records retrieved successfully
  - `401` — Unauthorized

##### POST /api/v1/klingOmni/batchDetail — Batch get Kling Omni video details
Get details of multiple Kling Omni tasks by their IDs (max 200). Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1KlingOmniBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/klingOmni/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized

##### GET /api/v1/klingOmni/{_id} — Get Kling Omni video detail
Get detailed information about a specific Kling Omni video generation task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1KlingOmniId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/klingOmni/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task detail retrieved successfully
  - `401` — Unauthorized
  - `404` — Task not found

##### PUT /api/v1/klingOmni/{_id} — Update Kling Omni video name
Update the name of a Kling Omni video generation task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `putApiV1KlingOmniId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- JSON body fields:
  - `name` (body, required; string; example: `My Task`) — New name for the task
- Example request:
```bash
curl -X PUT "https://cheap.dev/api/v1/klingOmni/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Task"
}
JSON
```
- Responses:
  - `200` — Updated successfully
  - `401` — Unauthorized
  - `404` — Task not found

##### DELETE /api/v1/klingOmni/{_id} — Delete Kling Omni video
Soft-delete a Kling Omni video generation task. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1KlingOmniId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/klingOmni/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Deleted successfully
  - `401` — Unauthorized
  - `404` — Task not found
#### Sora 2 Pro Video

##### POST /api/v1/soraVideo/start — Start Sora 2 Pro video generation (powered by Kling 3.0)
Generate videos using Kling 3.0 official API. Supports text-to-video and image-to-video. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1SoraVideoStart`
- JSON body fields:
  - `name` (body, optional; string) — Task name (optional)
  - `model_type` (body, optional; string; allowed: `text-to-video`, `image-to-video`; default: `image-to-video`) — Generation mode
  - `prompt` (body, required; string) — Text prompt for video generation
  - `image_urls` (body, optional; string[]) — Required when model_type=image-to-video
  - `aspect_ratio` (body, optional; string; allowed: `portrait`, `landscape`; default: `landscape`)
  - `duration_seconds` (body, optional; string; allowed: `5`, `10`, `15`; default: `5`)
  - `quality` (body, optional; string; allowed: `standard`, `high`; default: `standard`)
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/soraVideo/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "model_type": "image-to-video",
  "prompt": "<prompt>",
  "aspect_ratio": "landscape",
  "duration_seconds": "5",
  "quality": "standard",
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Task created successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/soraVideo/allRecords — List Sora 2 Pro records
allRecords - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1SoraVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — pageNum parameter
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — pageSize parameter
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/soraVideo/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — OK
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/soraVideo/batchDetail — Batch get Sora 2 Pro video task details
Query details for multiple Sora 2 Pro video tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1SoraVideoBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/soraVideo/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Task details
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/soraVideo/{_id} — Get Sora 2 Pro record detail
detail - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1SoraVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/soraVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — OK
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/soraVideo/{_id} — Delete Sora 2 Pro record
delete - HTTP DELETE Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1SoraVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/soraVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — OK
  - `401` — Unauthorized - Invalid or missing JWT token
#### Image Edit

##### POST /api/v1/userImageEdit/start — Start image editing task
Edit images using AI with different edit types like clothing or product editing Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImageEditStart`
- JSON body fields:
  - `name` (body, optional; string; default: ``; example: `Clothing Edit`) — Name of the image edit task
  - `edit_type` (body, required; string; allowed: `clothing`, `product`; example: `clothing`) — Type of edit to perform
  - `image_urls` (body, required; string[]; min items: 2; example: `["https://example.com/image1.jpg","https://example.com/image2.jpg"]`) — Array of image URLs to edit (minimum 2)
  - `timeout` (body, optional; number; default: `120`; example: `120`) — Processing timeout in seconds
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userImageEdit/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "Clothing Edit",
  "edit_type": "clothing",
  "image_urls": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "timeout": 120,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Image edit task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userImageEdit/allRecords — Get all task records
Retrieve paginated list of user's tasks Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserImageEditAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userImageEdit/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userImageEdit/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserImageEditBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userImageEdit/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userImageEdit/{_id} — Get task details
Retrieve detailed information about a specific task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserImageEditId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userImageEdit/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userImageEdit/{_id} — Delete task
Delete a specific task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserImageEditId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userImageEdit/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token

### Face & Body
#### Face Swap

##### POST /api/v1/userFaceSwapImage/add — Add a new face image for face swapping
Add a new face image to the user's face swap image collection Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserFaceSwapImageAdd`
- JSON body fields:
  - `face_url` (body, required; string; example: `https://example.com/face-image.jpg`) — URL of the face image to be used for face swapping
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userFaceSwapImage/add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "face_url": "https://example.com/face-image.jpg"
}
JSON
```
- Responses:
  - `200` — Face image added successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userFaceSwapImage/records — Get user's face swap image records
Retrieve all face swap images for the authenticated user Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFaceSwapImageRecords`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userFaceSwapImage/records" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Face swap image records retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userFaceSwapImage/{_id} — Remove a face swap image
Delete a specific face swap image from the user's collection Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserFaceSwapImageId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the face swap image to delete
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userFaceSwapImage/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Face swap image deleted successfully
  - `400` — Bad Request - Invalid ID format
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userFaceSwapPreview/add — Create a new face swap preview task
Create a face swap preview task using video and face image URLs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserFaceSwapPreviewAdd`
- JSON body fields:
  - `video_url` (body, required; string; example: `https://example.com/video.mp4`) — URL of the video to swap face in
  - `face_url` (body, required; string; example: `https://example.com/face.jpg`) — URL of the face image to swap with
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userFaceSwapPreview/add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "video_url": "https://example.com/video.mp4",
  "face_url": "https://example.com/face.jpg"
}
JSON
```
- Responses:
  - `200` — Face swap preview task created successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userFaceSwapPreview/status — Get face swap preview status
Check the processing status of a specific face swap preview task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFaceSwapPreviewStatus`
- Request parameters:
  - `_id` (query, required; string; example: `507f1f77bcf86cd799439011`) — ID of the face swap preview task
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userFaceSwapPreview/status?_id=507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Preview status retrieved successfully
  - `400` — Bad Request - Invalid task ID format
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userFaceSwapTask/add — Create a new face swap task
Create a face swap task with video, face image, and optional cover image Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserFaceSwapTaskAdd`
- JSON body fields:
  - `name` (body, required; string; example: `My Face Swap Video`) — Name of the face swap task
  - `video_url` (body, required; string; example: `https://example.com/video.mp4`) — URL of the video to swap face in
  - `face_url` (body, required; string; example: `https://example.com/face.jpg`) — URL of the face image to swap with
  - `cover_url` (body, optional; string; example: `https://example.com/cover.jpg`) — Optional cover image URL
  - `model_version` (body, optional; string; allowed: `v1`, `v2`; example: `v1`) — Face swap model version: v1 (JAH pipeline, default), v2 (ComfyUI, image only)
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userFaceSwapTask/add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Face Swap Video",
  "video_url": "https://example.com/video.mp4",
  "face_url": "https://example.com/face.jpg",
  "cover_url": "https://example.com/cover.jpg",
  "model_version": "v1",
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Face swap task created successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userFaceSwapTask/records — Get user's face swap task records
Retrieve paginated list of face swap tasks for the authenticated user Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFaceSwapTaskRecords`
- Request parameters:
  - `pageNum` (query, required; integer; default: `1`; min: 1; example: `1`) — Page number (starts from 1)
  - `pageSize` (query, required; integer; default: `10`; min: 1; max: 100; example: `10`) — Number of records per page
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userFaceSwapTask/records?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task records retrieved successfully
  - `400` — Bad Request - Invalid pagination parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userFaceSwapTask/status — Get user's face swap task status
Get overall face swap task status information for the authenticated user Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFaceSwapTaskStatus`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userFaceSwapTask/status" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task status retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userFaceSwapTask/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserFaceSwapTaskBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userFaceSwapTask/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userFaceSwapTask/{_id} — Get face swap task details
Retrieve detailed information about a specific face swap task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserFaceSwapTaskId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the face swap task
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userFaceSwapTask/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved successfully
  - `400` — Bad Request - Invalid task ID format
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userFaceSwapTask/{_id} — Delete face swap task
Delete a face swap task from the user's collection (DELETE method) Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserFaceSwapTaskId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the face swap task to delete
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userFaceSwapTask/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `400` — Bad Request - Invalid task ID format
  - `401` — Unauthorized - Invalid or missing JWT token
#### Head Swap

##### POST /api/v1/headSwap/start — Start head swap generation
Generate a head swap result by replacing the head in a target image/video with a source head. **Supported modes:** - **Image to Image**: Provide an image as `target_image_url` to get a head-swapped image - **Image to Video**: Provide a video as `target_image_url` to get a head-swapped video (max 15 seconds) **Content moderation:** - Minor detection is performed on input images - If a minor is detected (age < 10), the request will be rejected with code 1003 - If a suspected minor is detected (10 <= age < 15), set `minor_suspected_skip: true` to proceed **Async workflow:** 1. Task is created with status `initialized` 2. Task is queued and sent to algorithm service (status: `sent`) 3. Algorithm processes the task (status: `processing`) 4. Result is ready (status: `completed`) or failed (status: `failed`) 5. Use `/api/v1/headSwap/{_id}` to poll for status updates Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1HeadSwapStart`
- JSON body fields:
  - `image_url` (body, required; string; format: uri; example: `https://example.com/head.jpg`) — URL of the source head image (the head to be transplanted)
  - `target_image_url` (body, required; string; format: uri; example: `https://example.com/body.jpg`) — URL of the target body image or video (where the head will be placed)
  - `minor_suspected_skip` (body, optional; boolean; default: `false`; example: `false`) — Skip suspected minor warning (for ages 10-14). Use with caution.
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/headSwap/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "image_url": "https://example.com/head.jpg",
  "target_image_url": "https://example.com/body.jpg",
  "minor_suspected_skip": false,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Head swap task started successfully
  - `400` — Invalid request parameters or insufficient coins
  - `401` — Unauthorized - Invalid or missing JWT token
  - `403` — Content moderation failed (code 1003 = minor detected, code 1004 = suspected minor)

##### GET /api/v1/headSwap/allRecords — Get all head swap records
Get a paginated list of the current user's head swap tasks. Results are sorted by creation time (newest first) and filtered by expiration. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1HeadSwapAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number (starts from 1)
  - `pageSize` (query, optional; integer; default: `10`; min: 1; max: 100; example: `10`) — Number of items per page
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/headSwap/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Head swap records retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/headSwap/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1HeadSwapBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/headSwap/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/headSwap/{_id} — Get head swap task detail
Get detailed information of a specific head swap task by ID Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1HeadSwapId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Head swap task ID (MongoDB ObjectId)
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/headSwap/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task detail retrieved successfully
  - `400` — Invalid task ID format
  - `401` — Unauthorized - Invalid or missing JWT token
  - `404` — Task not found

##### DELETE /api/v1/headSwap/{_id} — Delete head swap task
Delete a head swap task by ID. **Status behavior:** - `initialized`: Can be deleted with coin refund (task not yet sent to algorithm service) - `sent/pending/processing`: Cannot be deleted, returns 400 error (task is processing) - `completed/failed`: Can be deleted without refund (task already completed or failed) Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1HeadSwapId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Head swap task ID (MongoDB ObjectId)
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/headSwap/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `400` — Cannot delete task in processing state
  - `401` — Unauthorized - Invalid or missing JWT token
  - `404` — Task not found
#### Actor Swap

##### POST /api/v1/actorSwap/start — Start actor swap task
Generate actor swap video by swapping actor from image to video Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1ActorSwapStart`
- JSON body fields:
  - `name` (body, optional; string; example: `My Actor Swap`) — Name of the actor swap task
  - `image_url` (body, required; string; format: uri; example: `https://example.com/actor.jpg`) — URL of the reference actor image
  - `video_url` (body, required; string; format: uri; example: `https://example.com/video.mp4`) — URL of the control video
  - `prompt` (body, optional; string; example: `high quality, realistic`) — Positive prompt for generation
  - `negative_prompt` (body, optional; string; example: `blurry, distorted`) — Negative prompt to avoid unwanted features
  - `timeout` (body, optional; integer; default: `300`; example: `300`) — Timeout in seconds
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/actorSwap/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Actor Swap",
  "image_url": "https://example.com/actor.jpg",
  "video_url": "https://example.com/video.mp4",
  "prompt": "high quality, realistic",
  "negative_prompt": "blurry, distorted",
  "timeout": 300,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Actor swap task started successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/actorSwap/allRecords — Get all task records
Retrieve paginated list of user's tasks Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1ActorSwapAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/actorSwap/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/actorSwap/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1ActorSwapBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/actorSwap/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/actorSwap/{_id} — Get task details
Retrieve detailed information about a specific task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1ActorSwapId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/actorSwap/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/actorSwap/{_id} — Delete task
Delete a specific task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1ActorSwapId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/actorSwap/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token
#### Talking Photo

##### POST /api/v1/talkingPhoto/start — Start talking photo generation
Generate a talking photo from image and audio/text prompt Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1TalkingPhotoStart`
- JSON body fields:
  - `name` (body, required; string; example: `My Talking Photo`) — Name of the talking photo task
  - `image_url` (body, required; string; example: `https://example.com/photo.jpg`) — URL of the source image
  - `audio_url` (body, optional; string; example: `https://example.com/audio.mp3`) — Optional audio URL
  - `duration` (body, optional; integer; default: `3`; min: 1; max: 20; example: `5`) — Duration in seconds
  - `prompt` (body, required; string; example: `Make this person smile and speak`) — Generation prompt
  - `negative_prompt` (body, required; string; example: `blurry, distorted`) — Negative prompt to avoid unwanted features
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/talkingPhoto/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Talking Photo",
  "image_url": "https://example.com/photo.jpg",
  "audio_url": "https://example.com/audio.mp3",
  "duration": 5,
  "prompt": "Make this person smile and speak",
  "negative_prompt": "blurry, distorted",
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Talking photo task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/talkingPhoto/allRecords — Get all task records
Retrieve paginated list of user's tasks Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1TalkingPhotoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/talkingPhoto/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/talkingPhoto/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1TalkingPhotoBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/talkingPhoto/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/talkingPhoto/{_id} — Get task details
Retrieve detailed information about a specific task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1TalkingPhotoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/talkingPhoto/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/talkingPhoto/{_id} — Delete task
Delete a specific task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1TalkingPhotoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/talkingPhoto/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token
#### Talking Video

##### POST /api/v1/talkingVideo/start — Start talking video generation
Generate a talking video from video and audio/text prompt Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1TalkingVideoStart`
- JSON body fields:
  - `name` (body, required; string; example: `My Talking Video`) — Name of the talking video task
  - `video_url` (body, required; string; example: `https://example.com/video.mp4`) — URL of the source video
  - `audio_url` (body, optional; string; example: `https://example.com/audio.mp3`) — Optional audio URL
  - `duration` (body, optional; integer; default: `3`; min: 1; max: 20; example: `5`) — Duration in seconds
  - `prompt` (body, required; string; example: `Make this person smile and speak`) — Generation prompt
  - `negative_prompt` (body, required; string; example: `blurry, distorted`) — Negative prompt to avoid unwanted features
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/talkingVideo/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Talking Video",
  "video_url": "https://example.com/video.mp4",
  "audio_url": "https://example.com/audio.mp3",
  "duration": 5,
  "prompt": "Make this person smile and speak",
  "negative_prompt": "blurry, distorted",
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Talking video task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/talkingVideo/allRecords — Get all task records
Retrieve paginated list of user's tasks Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1TalkingVideoAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/talkingVideo/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/talkingVideo/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1TalkingVideoBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/talkingVideo/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/talkingVideo/{_id} — Get task details
Retrieve detailed information about a specific task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1TalkingVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/talkingVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/talkingVideo/{_id} — Delete task
Delete a specific task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1TalkingVideoId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/talkingVideo/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token
#### Virtual Try-On

##### POST /api/v1/virtualTryOn/start — Start virtual try-on task
Start a virtual try-on task with clothing images on person photos Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1VirtualTryOnStart`
- JSON body fields:
  - `name` (body, optional; string; default: ``; example: `Summer Dress Try-On`) — Name of the virtual try-on task
  - `image_urls` (body, required; string[]; min items: 2; max items: 4; example: `["https://example.com/person.jpg","https://example.com/dress.jpg"]`) — Array of 2 image URLs - [0] person image, [1] clothing image
  - `timeout` (body, optional; number; default: `120`; example: `120`) — Processing timeout in seconds
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/virtualTryOn/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "Summer Dress Try-On",
  "image_urls": [
    "https://example.com/person.jpg",
    "https://example.com/dress.jpg"
  ],
  "timeout": 120,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Virtual try-on task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/virtualTryOn/allRecords — Get all virtual try-on records
Retrieve paginated list of virtual try-on tasks for the current user Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1VirtualTryOnAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number for pagination
  - `pageSize` (query, optional; integer; default: `10`; min: 1; max: 100; example: `10`) — Number of items per page
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/virtualTryOn/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Virtual try-on records retrieved successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/virtualTryOn/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1VirtualTryOnBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/virtualTryOn/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/virtualTryOn/{_id} — Get virtual try-on task detail
Retrieve detailed information of a virtual try-on task by its ID Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1VirtualTryOnId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Virtual try-on task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/virtualTryOn/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Virtual try-on task detail retrieved successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/virtualTryOn/{_id} — Delete virtual try-on task
Delete a virtual try-on task by its ID Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1VirtualTryOnId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Virtual try-on task ID
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/virtualTryOn/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Virtual try-on task deleted successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token
#### Motion Transfer

##### POST /api/v1/motionTransfer/start — Start motion transfer task
Start a motion transfer task to transfer motion from video to image Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1MotionTransferStart`
- JSON body fields:
  - `name` (body, optional; string; default: ``; example: `Dance Motion Transfer`) — Name of the motion transfer task
  - `image_url` (body, required; string; format: uri; example: `https://example.com/person.jpg`) — Reference image URL for motion transfer
  - `video_url` (body, required; string; format: uri; example: `https://example.com/dance.mp4`) — Control video URL for motion source
  - `positive_prompt` (body, optional; string; example: `high quality motion transfer, natural pose transition, smooth movement`) — Positive prompt for motion transfer
  - `negative_prompt` (body, optional; string; example: `blurry, distorted limbs, unnatural poses, deformation`) — Negative prompt for motion transfer
  - `timeout` (body, optional; number; default: `300`; example: `300`) — Processing timeout in seconds
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/motionTransfer/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "Dance Motion Transfer",
  "image_url": "https://example.com/person.jpg",
  "video_url": "https://example.com/dance.mp4",
  "positive_prompt": "high quality motion transfer, natural pose transition, smooth movement",
  "negative_prompt": "blurry, distorted limbs, unnatural poses, deformation",
  "timeout": 300,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Motion transfer task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/motionTransfer/allRecords — Get all motion transfer records
Retrieve paginated list of motion transfer tasks for the current user Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1MotionTransferAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number for pagination
  - `pageSize` (query, optional; integer; default: `10`; min: 1; max: 100; example: `10`) — Number of items per page
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/motionTransfer/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Motion transfer records retrieved successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/motionTransfer/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1MotionTransferBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/motionTransfer/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/motionTransfer/{_id} — Get motion transfer task detail
Retrieve detailed information of a motion transfer task by its ID Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1MotionTransferId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Motion transfer task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/motionTransfer/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Motion transfer task detail retrieved successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/motionTransfer/{_id} — Delete motion transfer task
Delete a motion transfer task by its ID Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1MotionTransferId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Motion transfer task ID
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/motionTransfer/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Motion transfer task deleted successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token
#### Product Avatar

##### POST /api/v1/productAvatar/start — Generate product avatar with AI (Async)
Generate AI-powered product avatar by combining product and person images with customizable positioning and styling. **⚠️ IMPORTANT: This is an ASYNCHRONOUS operation** ### Async Workflow 1. **Submit Task** - Call this endpoint to create a new generation task - Returns immediately with task `_id` and status `initialized` - Task is queued for processing 2. **Processing States** - The task goes through these states: - `initialized` → Task created, waiting in queue - `sent` → Task submitted to AI service - `pending` → Task received by AI service - `processing` → AI is generating the image - `completed` → Generation finished successfully - `failed` → Generation failed (check `failed_message`) 3. **Get Results** - Poll for task status and results: - Use `GET /api/v1/productAvatar/{_id}` to check status - Use `GET /api/v1/productAvatar/allRecords` to list all tasks - When `current_status` is `completed`, `result_image_url` contains the generated image 4. **Timeout Handling**: - Tasks timeout after 2 hours and automatically fail - Credits are automatically refunded on timeout or failure ### Best Practices - Poll every 3-5 seconds to check task status - Handle both `completed` and `failed` states - Store the returned `_id` to query results later Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1ProductAvatarStart`
- JSON body fields:
  - `name` (body, optional; string; example: `My Product Avatar`) — Name for the product avatar generation task (optional)
  - `image_urls` (body, required; string[]; min items: 2; max items: 2; example: `["https://example.com/product.jpg","https://example.com/person.jpg"]`) — Array of image URLs - [0] product image, [1] person image
  - `product_rect` (body, required; object) — Product positioning and transformation parameters
  - `prompt` (body, optional; string; example: `Professional product showcase`) — Additional prompt for AI generation (optional)
  - `timeout` (body, optional; number; default: `120`; example: `120`) — Processing timeout in seconds
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/productAvatar/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Product Avatar",
  "image_urls": [
    "https://example.com/product.jpg",
    "https://example.com/person.jpg"
  ],
  "product_rect": {
    "x": 100,
    "y": 150,
    "width": 200,
    "height": 300,
    "rotation": 0,
    "scale": 1
  },
  "prompt": "Professional product showcase",
  "timeout": 120,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Product avatar generation started successfully
  - `400` — Bad Request - Invalid parameters or missing required fields
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/productAvatar/allRecords — List all product avatar tasks
Retrieve a paginated list of all product avatar generation tasks for the authenticated user. Use this endpoint to monitor task progress and retrieve results. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1ProductAvatarAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number (starting from 1)
  - `pageSize` (query, optional; integer; default: `10`; example: `10`) — Number of items per page
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/productAvatar/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successfully retrieved task list
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/productAvatar/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1ProductAvatarBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/productAvatar/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/productAvatar/{_id} — Query task status and get result
Retrieve detailed information about a specific product avatar generation task. Use this endpoint to poll for task status and get the result when completed. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1ProductAvatarId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID returned from the start endpoint
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/productAvatar/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successfully retrieved task details
  - `400` — Bad Request - Invalid task ID
  - `401` — Unauthorized - Invalid or missing JWT token
  - `404` — Task not found

##### DELETE /api/v1/productAvatar/{_id} — Delete a product avatar task
Soft delete a product avatar task. The task data will be marked as deleted but not removed from the database. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1ProductAvatarId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/productAvatar/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `400` — Bad Request - Invalid task ID
  - `401` — Unauthorized - Invalid or missing JWT token
  - `404` — Task not found
#### Photobook

##### POST /api/v1/userPhotobook/start — Start photobook generation
Create a photobook generation task using one face image and optional location/clothing prompts. The service will generate 4, 8, 12, or 16 final photos depending on total_count. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserPhotobookStart`
- JSON body fields:
  - `name` (body, optional; string; example: `Summer Travel Album`) — Display name for this photobook batch
  - `face_image_url` (body, required; string; example: `https://example.com/face.jpg`) — Source face image URL used for all generated photos
  - `location` (body, optional; string; example: `Paris street cafe at golden hour`) — Scene or location prompt
  - `clothing` (body, optional; string; example: `elegant white dress`) — Clothing prompt applied during the image edit step
  - `total_count` (body, optional; integer; allowed: `4`, `8`, `12`, `16`; default: `4`; example: `8`) — Total number of photos to generate
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userPhotobook/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "Summer Travel Album",
  "face_image_url": "https://example.com/face.jpg",
  "location": "Paris street cafe at golden hour",
  "clothing": "elegant white dress",
  "total_count": 8
}
JSON
```
- Responses:
  - `200` — Photobook task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userPhotobook/allRecords — Get photobook records
List the current user's photobook records with pagination. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserPhotobookAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; example: `1`) — Page number
  - `pageSize` (query, optional; integer; default: `20`; example: `20`) — Page size
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userPhotobook/allRecords?pageNum=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Photobook records retrieved successfully
  - `400` — Bad Request - Invalid pagination parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userPhotobook/{id} — Get photobook record detail
Get one photobook record by id. The endpoint also syncs the latest pipeline status before returning. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserPhotobookId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Photobook record id
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userPhotobook/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Photobook record detail retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token
  - `404` — Record not found

##### DELETE /api/v1/userPhotobook/{id} — Delete photobook record
Delete one photobook record owned by the current user. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserPhotobookId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Photobook record id
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userPhotobook/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Photobook record deleted successfully
  - `400` — Bad Request - Photobook record cannot be deleted in its current status (for example, processing)
  - `401` — Unauthorized - Invalid or missing JWT token
  - `404` — Not Found - Photobook record does not exist or is not accessible by the current user

### Avatar & Video
#### Generate Avatar Videos

##### POST /api/v1/anchor/list — List available avatars
Returns the system and user-specific avatars available to the authenticated API user. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1AnchorList`
- JSON body fields:
  - `web_type` (body, optional; string; allowed: `a2e`, `tyzn`; example: `a2e`) — Optional client type. Use a2e or tyzn to include default system avatars alongside user-specific avatars.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/anchor/list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "web_type": "a2e"
}
JSON
```
- Responses:
  - `200` — Operation completed successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/video/generate — Generate AI video with avatar
Generate AI video with avatar using audio source and selected avatar. Either audioSrc or custom_voice is required. For background replacement, use back_id for system backgrounds or custom_back_id for backgrounds created by /api/v1/custom_back/add. The avatar must have an original background saved, or the request must provide anchor_background_img or anchor_background_color. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1VideoGenerate`
- JSON body fields:
  - `title` (body, optional; string; max length: 40; example: `My AI Video`) — Video title (optional, max 40 characters)
  - `audioSrc` (body, optional; string; example: `https://example.com/audio.mp3`) — Audio source URL (required if custom_voice not provided)
  - `custom_voice` (body, optional; string; example: `https://example.com/custom_voice.wav`) — Custom voice audio URL (required if audioSrc not provided)
  - `anchor_id` (body, required; string; example: `507f1f77bcf86cd799439011`) — Avatar/anchor ID (MongoDB ObjectId)
  - `anchor_type` (body, required; number; example: `0`) — Avatar type (0 for system avatar, 1 for custom avatar)
  - `anchor_background_img` (body, optional; string; example: `https://example.com/original-avatar-background.jpg`) — Original avatar background image URL. Required for background replacement if the avatar record does not already have background_img or background_color.
  - `anchor_background_color` (body, optional; string; example: `rgba(255,255,255,1)`) — Original avatar background color in RGBA format. Required for background replacement if the avatar record does not already have background_img or background_color.
  - `back_id` (body, optional; string; example: `507f1f77bcf86cd799439012`) — System background template ID (MongoDB ObjectId). Mutually exclusive with custom_back_id; sending both returns error 30005.
  - `face_swap_id` (body, optional; string; example: `507f1f77bcf86cd799439013`) — Face swap template ID (MongoDB ObjectId)
  - `custom_back_id` (body, optional; string; example: `507f1f77bcf86cd799439014`) — Custom background ID returned by /api/v1/custom_back/add (MongoDB ObjectId). Mutually exclusive with back_id; sending both returns error 30005.
  - `color` (body, optional; string; example: `rgba(0,0,0,1)`) — Color setting in RGBA format
  - `wl_model` (body, optional; string; example: `default`) — Watermark/logo model setting
  - `isSkipRs` (body, optional; boolean; example: `false`) — Skip resolution scaling
  - `web_bg_width` (body, optional; number; default: `0`; example: `1920`) — Output canvas/background width. Required when using back_id, custom_back_id, or color.
  - `web_bg_height` (body, optional; number; default: `0`; example: `1080`) — Output canvas/background height. Required when using back_id, custom_back_id, or color.
  - `web_people_width` (body, optional; number; default: `0`; example: `800`) — Avatar width in output layout. Required when using back_id, custom_back_id, or color.
  - `web_people_height` (body, optional; number; default: `0`; example: `600`) — Avatar height in output layout. Required when using back_id, custom_back_id, or color.
  - `web_people_x` (body, optional; number; default: `0`; example: `100`) — Avatar X position in web layout
  - `web_people_y` (body, optional; number; default: `0`; example: `50`) — Avatar Y position in web layout
  - `web_dist_bg_width` (body, optional; number; default: `-1`; example: `1920`) — Distributed background width
  - `web_dist_bg_height` (body, optional; number; default: `-1`; example: `1080`) — Distributed background height
  - `web_dist_bg_x` (body, optional; number; default: `0`; example: `0`) — Distributed background X position
  - `web_dist_bg_y` (body, optional; number; default: `0`; example: `0`) — Distributed background Y position
  - `resolution` (body, optional; number; default: `1080`; example: `1080`) — Video resolution (height in pixels)
  - `msg` (body, optional; string; example: `Custom video generation`) — Additional message or notes
  - `erode_factor` (body, optional; number; example: `0.5`) — Erosion factor for image processing
  - `isSkipGp` (body, optional; boolean; example: `false`) — Skip green screen processing
  - `isCaptionEnabled` (body, optional; boolean; example: `true`) — Enable captions/subtitles
  - `gp_model` (body, optional; object) — Green screen processing model settings
  - `isToPublicPool` (body, optional; boolean; example: `false`) — Add to public pool for sharing
  - `lip_model` (body, optional; string; example: `default`) — Lip sync model selection
  - `captionAlign` (body, optional; object) — Caption alignment and styling settings
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/video/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "title": "My AI Video",
  "audioSrc": "https://example.com/audio.mp3",
  "anchor_id": "507f1f77bcf86cd799439011",
  "anchor_type": 0
}
JSON
```
- Responses:
  - `200` — Video generation started successfully
  - `400` — Bad Request - Invalid parameters or missing required audio source
  - `401` — Unauthorized - Invalid or missing JWT token
#### Create Avatars

##### POST /api/v1/custom_avatar/add — Add new record
Add new item - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomAvatarAdd`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/custom_avatar/add" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Item created successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/custom_avatar/list — Create/Run list
List items - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomAvatarList`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/custom_avatar/list" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Item retrieved successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/custom_avatar/del — Delete record
del - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomAvatarDel`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/custom_avatar/del" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Operation completed successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/custom_avatar/all_tags — List all tags
all tags - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1CustomAvatarAllTags`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/custom_avatar/all_tags" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Operation completed successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### PUT /api/v1/custom_avatar/{_id} — Update record
update - HTTP PUT Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `putApiV1CustomAvatarId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X PUT "https://cheap.dev/api/v1/custom_avatar/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token
#### Background Matting

##### POST /api/v1/custom_back/add — Add new custom background
Upload and add a new custom background image - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomBackAdd`
- JSON body fields:
  - `img_url` (body, required; string; example: `https://example.com/background.jpg`) — URL of the background image to add
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/custom_back/add" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "img_url": "https://example.com/background.jpg"
}
JSON
```
- Responses:
  - `200` — Background item created successfully
  - `400` — Bad Request - Invalid parameters or missing img_url
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/custom_back/list — Create/Run list
List items - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomBackList`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/custom_back/list" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Item retrieved successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/custom_back/del — Delete record
del - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomBackDel`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/custom_back/del" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Operation completed successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/custom_back/allBackground — List all backgrounds
allBackground - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1CustomBackAllBackground`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/custom_back/allBackground" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/custom_back/randomBackground — Get a random background
randomBackground - HTTP POST
- Operation ID: `postApiV1CustomBackRandomBackground`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/custom_back/randomBackground" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
#### Video Twin

##### POST /api/v1/userVideoTwin/upload — Upload file
upload - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinUpload`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userVideoTwin/upload" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userVideoTwin/training — Start training
training - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinTraining`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userVideoTwin/training" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userVideoTwin/uploadStatus — Get video twin upload status
Check the upload status of video twin files for the authenticated user Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVideoTwinUploadStatus`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userVideoTwin/uploadStatus" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Upload status retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userVideoTwin/userRecords — Get user video twin records
Retrieve all video twin records for the authenticated user Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVideoTwinUserRecords`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userVideoTwin/userRecords" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Video twin records retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userVideoTwin/remove — Remove video twin
Remove a video twin from the user's collection Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinRemove`
- JSON body fields:
  - `_id` (body, required; string; example: `507f1f77bcf86cd799439011`) — ID of the video twin to remove
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userVideoTwin/remove" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "_id": "507f1f77bcf86cd799439011"
}
JSON
```
- Responses:
  - `200` — Video twin removed successfully
  - `400` — Bad Request - Invalid video twin ID
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userVideoTwin/records — Get video twin records
Retrieve paginated video twin records with optional filters Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVideoTwinRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number (starts from 1)
  - `pageSize` (query, optional; integer; default: `10`; min: 1; max: 100; example: `10`) — Number of records per page
  - `status` (query, optional; string; allowed: `pending`, `processing`, `completed`, `failed`; example: `completed`) — Filter by status
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userVideoTwin/records?pageNum=1&pageSize=10&status=completed" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Records retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userVideoTwin/startTraining — Start video twin training
Begin training a new video twin model with image or video source Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinStartTraining`
- JSON body fields:
  - `name` (body, optional; string; example: `My Video Twin`) — Name for the video twin
  - `image_url` (body, optional; string; example: `https://example.com/face.jpg`) — URL of the source image
  - `video_url` (body, optional; string; example: `https://example.com/video.mp4`) — URL of the source video
  - `video_background_image` (body, optional; string; example: `https://example.com/bg.jpg`) — URL of background image
  - `video_background_color` (body, optional; string; example: `rgba(255,255,255,1)`) — Background color in RGBA format
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userVideoTwin/startTraining" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Video Twin",
  "image_url": "https://example.com/face.jpg",
  "video_url": "https://example.com/video.mp4",
  "video_background_image": "https://example.com/bg.jpg",
  "video_background_color": "rgba(255,255,255,1)"
}
JSON
```
- Responses:
  - `200` — Video twin training started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userVideoTwin/continueTraining — Continue video twin training
Continue training an existing video twin model that was previously paused Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinContinueTraining`
- JSON body fields:
  - `_id` (body, required; string; example: `507f1f77bcf86cd799439011`) — ID of the video twin to continue training
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userVideoTwin/continueTraining" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "_id": "507f1f77bcf86cd799439011"
}
JSON
```
- Responses:
  - `200` — Training continued successfully
  - `400` — Bad Request - Invalid video twin ID
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userVideoTwin/trainingRecords — Get training records
Retrieve all video twin training records for the authenticated user Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVideoTwinTrainingRecords`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userVideoTwin/trainingRecords" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Training records retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userVideoTwin/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userVideoTwin/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userVideoTwin/{_id} — Get record details
detail - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVideoTwinId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — _id parameter
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userVideoTwin/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userVideoTwin/retry — Retry a failed task
retry - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinRetry`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userVideoTwin/retry" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userVideoTwin/eyeContact — Start eye contact enhancement
Enhance video twin with improved eye contact using AI processing Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVideoTwinEyeContact`
- JSON body fields:
  - `_id` (body, optional; string; example: `507f1f77bcf86cd799439011`) — ID of the video twin to enhance
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userVideoTwin/eyeContact" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "_id": "507f1f77bcf86cd799439011"
}
JSON
```
- Responses:
  - `200` — Eye contact enhancement started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

### Voice & Audio
#### TTS and Voice Clone

##### POST /api/v1/anchor/tts_list — List system voices (TTS presets)
List available system TTS voices/presets for the current user. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1AnchorTtsList`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/anchor/tts_list" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Voice preset list
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/anchor/language_list — List supported languages/regions for voices
List supported language & region options. Optional `voice_map_type` can be used to filter results. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1AnchorLanguageList`
- JSON body fields:
  - `voice_map_type` (body, optional; string; example: `en-US`) — Filter by locale mapping type (e.g. en-US)
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/anchor/language_list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "voice_map_type": "en-US"
}
JSON
```
- Responses:
  - `200` — Language/region list
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/anchor/voice_list — List available voices by country/region
List available voices filtered by `country`, `region`, and `voice_map_type`. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1AnchorVoiceList`
- JSON body fields:
  - `country` (body, optional; string; example: `en`) — Country/language code (default en)
  - `region` (body, optional; string; example: `US`) — Region code (default US)
  - `voice_map_type` (body, optional; string; example: `en-US`) — Locale mapping type (default en-US)
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/anchor/voice_list" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "country": "en",
  "region": "US",
  "voice_map_type": "en-US"
}
JSON
```
- Responses:
  - `200` — Voice list
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/anchor/voice_list — List available voices (GET)
List available voices. Defaults: country=en, region=US, voice_map_type=en-US. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1AnchorVoiceList`
- Request parameters:
  - `country` (query, optional; string; default: `en`; example: `en`) — country parameter
  - `region` (query, optional; string; default: `US`; example: `US`) — region parameter
  - `voice_map_type` (query, optional; string; default: `en-US`; example: `en-US`) — voice_map_type parameter
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/anchor/voice_list?country=en&region=US&voice_map_type=en-US" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Item retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/video/send_tts — Generate text-to-speech audio
Convert text to speech using AI voices with customizable parameters. ### Voice Selection Must provide **either** `tts_id` (system voice) **or** `user_voice_id` (custom cloned voice): - `tts_id`: Use built-in system voice (400+ voices available) - `user_voice_id`: Use your own custom cloned voice (requires `country` and `region` parameters) ### Text Limitations - **API users**: Maximum 1000 characters per request - **Web users**: Maximum 3000 characters per request - Text length is calculated including all Unicode characters ### Rate Limiting & Captcha For non-API users, captcha verification may be required after frequent usage: - Use `type` parameter to specify captcha type (`turnstile` or `aliyun_captcha`) - Provide corresponding `turnstile_token` or `captchaVerifyParam` when captcha is required - API token users skip captcha verification Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1VideoSendTts`
- JSON body fields:
  - `msg` (body, required; string; min length: 1; max length: 3000; example: `Welcome. Let's start your AI journey.`) — Text content to convert to speech (1-3000 characters)
  - `tts_id` (body, optional; string; example: `66dc3c1b7dc1f1c483cc5ab8`) — System voice ID (MongoDB ObjectId). Must provide either tts_id or user_voice_id.
  - `user_voice_id` (body, optional; string; example: `66f1234567890abcdef12345`) — Custom cloned voice ID (MongoDB ObjectId). Must provide either tts_id or user_voice_id.
  - `country` (body, optional; string; default: `en`; example: `en`) — Locale language part (e.g. 'en', 'zh', 'pt', 'ja'). Optional when using user_voice_id, defaults to 'en'. Combine with `region` to form locale like 'en-US'/'zh-CN'. Values should come from POST /api/v1/anchor/language_list (top-level `value`).
  - `region` (body, optional; string; default: `US`; example: `US`) — Locale region part (e.g. 'US', 'CN', 'BR', 'JP'). Optional when using user_voice_id, defaults to 'US'. Combine with `country` to form locale like 'en-US'/'zh-CN'. Values should come from POST /api/v1/anchor/language_list (child `value`).
  - `speechRate` (body, optional; number; default: `1`; min: 0.5; max: 2; example: `1`) — Speech speed multiplier (0.5-2.0)
  - `type` (body, optional; string; allowed: `turnstile`, `aliyun_captcha`; example: `turnstile`) — Captcha type (required when captcha verification is needed)
  - `turnstile_token` (body, optional; string; example: `0x4AAAAAAxxxxxxxxxxxxxxxxxx`) — Captcha token (required when type is 'turnstile')
  - `captchaVerifyParam` (body, optional; string; example: `xxxxxxxxxxxx`) — Captcha verification parameter (required when type is 'aliyun_captcha')
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/video/send_tts" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "msg": "Welcome. Let's start your AI journey.",
  "tts_id": "66dc3c1b7dc1f1c483cc5ab8",
  "user_voice_id": "66f1234567890abcdef12345",
  "country": "en",
  "region": "US",
  "speechRate": 1,
  "type": "turnstile",
  "turnstile_token": "0x4AAAAAAxxxxxxxxxxxxxxxxxx",
  "captchaVerifyParam": "xxxxxxxxxxxx"
}
JSON
```
- Responses:
  - `200` — Text-to-speech generation successful
  - `400` — Invalid request parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/tts/preview/list — Get TTS preview list
Get TTS preview list for current user (last 24 hours only) - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1TtsPreviewList`
- Request parameters:
  - `pageSize` (query, optional; integer; default: `20`; min: 1; max: 100; example: `20`) — Number of items per page
  - `current` (query, optional; integer; default: `1`; min: 1; example: `1`) — Current page number
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/tts/preview/list?pageSize=20&current=1" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — TTS preview list retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/tts/preview/{id} — Delete TTS preview record
Soft delete a TTS preview record for current user - HTTP DELETE Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1TtsPreviewId`
- Request parameters:
  - `id` (path, required; string; example: `507f1f77bcf86cd799439011`) — TTS preview record ID to delete
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/tts/preview/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — TTS preview record deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token
  - `404` — Record not found

##### POST /api/v1/userVoice/training — Start voice training
发起声音克隆训练任务（异步）。 - **并发限制**：同一用户短时间内只允许同时发起 1 个训练请求（服务端有并发保护）。 - **费用**：不同 `model` 可能会消耗不同数量的金币；若创建失败会自动回退扣费。 - **结果状态**：创建成功后可通过 `GET /api/v1/userVoice/trainingRecord` 查看最新记录及 `current_status`。 Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserVoiceTraining`
- JSON body fields:
  - `name` (body, required; string; example: `My Custom Voice`) — Name of the voice model
  - `voice_urls` (body, required; string[]; min items: 1; example: `["https://example.com/audio1.wav","https://example.com/audio2.wav"]`) — Array of audio file URLs for training
  - `gender` (body, optional; string; allowed: `female`, `male`; default: `female`; example: `female`) — Voice gender
  - `denoise` (body, optional; boolean; example: `true`) — Whether to apply denoising
  - `enhance_voice_similarity` (body, optional; boolean; example: `true`) — Whether to enhance voice similarity
  - `model` (body, optional; string; allowed: `a2e`, `cartesia`, `minimax`, `elevenlabs`; default: `a2e`; example: `a2e`) — Voice model to use
  - `language` (body, optional; string; example: `en-US`) — Language code from client (e.g. en-US, zh-CN). If omitted, server will infer from request headers.
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userVoice/training" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Custom Voice",
  "voice_urls": [
    "https://example.com/audio1.wav",
    "https://example.com/audio2.wav"
  ],
  "gender": "female",
  "denoise": true,
  "enhance_voice_similarity": true,
  "model": "a2e",
  "language": "en-US",
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Voice training record created successfully
  - `400` — Bad Request - Invalid training data
  - `401` — Unauthorized - Invalid or missing JWT token
  - `403` — Forbidden - Voice clone limit exceeded

##### GET /api/v1/userVoice/trainingRecord — Get voice training records
获取当前登录用户的声音克隆训练记录列表（包含进行中/已完成/失败等状态）。 - **排序**：按 `createdAt` 倒序（最新在前）。 - **状态字段**：`current_status` 可能值包含 `sent` / `pendding` / `processing` / `completed` / `failed`。 Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVoiceTrainingRecord`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userVoice/trainingRecord" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userVoice/completedRecord — Get completed voice training records
获取当前登录用户 **已完成** 的声音克隆训练记录列表（`current_status=completed`）。 - **排序**：按 `createdAt` 倒序（最新在前）。 Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVoiceCompletedRecord`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userVoice/completedRecord" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userVoice/{_id} — Delete voice training record
软删除一条声音克隆训练记录（仅将 `deleted=true`，不会物理删除数据）。 Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserVoiceId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — MongoDB ObjectId of the voice training record
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userVoice/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userVoice/{_id} — Get voice training record detail
根据记录 `_id` 查询单条声音克隆训练记录详情。 Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserVoiceId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — MongoDB ObjectId of the voice training record
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userVoice/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request - Invalid _id
  - `401` — Unauthorized - Invalid or missing JWT token

##### PUT /api/v1/userVoice/{_id} — Update voice training record name
更新指定记录的 `name`（用于重命名）。 Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `putApiV1UserVoiceId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — MongoDB ObjectId of the voice training record
- JSON body fields:
  - `name` (body, required; string; example: `My Renamed Voice`) — New name of the voice record
- Example request:
```bash
curl -X PUT "https://cheap.dev/api/v1/userVoice/507f1f77bcf86cd799439011" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Renamed Voice"
}
JSON
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request - Invalid request body
  - `401` — Unauthorized - Invalid or missing JWT token
#### AI Dubbing

##### POST /api/v1/userDubbing/startDubbing — Start AI dubbing task
startDubbing - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserDubbingStartDubbing`
- JSON body fields:
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userDubbing/startDubbing" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userDubbing/allRecords — Get all task records
Retrieve paginated list of user's tasks Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserDubbingAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userDubbing/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userDubbing/allProcessing — List processing records
allProcessing - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserDubbingAllProcessing`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userDubbing/allProcessing" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userDubbing/{_id} — Get task details
Retrieve detailed information about a specific task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserDubbingId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userDubbing/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userDubbing/{_id} — Delete dubbing task
Delete a specific dubbing task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserDubbingId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the dubbing task
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userDubbing/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `400` — Bad Request - Invalid task ID
  - `401` — Unauthorized - Invalid or missing JWT token
#### ThinkSound

##### POST /api/v1/thinkSound/start — Start ThinkSound generation
Generate audio-visual content from video using AI with customizable parameters Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1ThinkSoundStart`
- JSON body fields:
  - `name` (body, optional; string; example: `My Audio-Visual Generation`) — Name of the ThinkSound task
  - `video_url` (body, required; string; example: `https://example.com/video.mp4`) — URL of the source video (must be .mp4, .avi, .mov, or .mkv)
  - `caption` (body, optional; string; default: ``; example: `Generate audio for this silent video`) — Caption for the generation
  - `cot_description` (body, optional; string; default: ``; example: `Detailed description of the audio generation process`) — Chain of thought description
  - `seed` (body, optional; number; example: `12345`) — Random seed for reproducible results
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/thinkSound/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "My Audio-Visual Generation",
  "video_url": "https://example.com/video.mp4",
  "caption": "Generate audio for this silent video",
  "cot_description": "Detailed description of the audio generation process",
  "seed": 12345,
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — ThinkSound generation started successfully
  - `400` — Bad Request - Invalid parameters or video format
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/thinkSound/{_id} — Delete ThinkSound task
Delete a specific ThinkSound generation task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1ThinkSoundId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the ThinkSound task to delete
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/thinkSound/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — ThinkSound task deleted successfully
  - `400` — Bad Request - Invalid task ID
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/thinkSound/{_id} — Get ThinkSound task details
Retrieve detailed information about a specific ThinkSound generation task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1ThinkSoundId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the ThinkSound task
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/thinkSound/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — ThinkSound task details retrieved successfully
  - `400` — Bad Request - Invalid task ID format
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/thinkSound/allRecords — Get all ThinkSound records
Retrieve paginated list of ThinkSound generation tasks for the authenticated user Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1ThinkSoundAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number (starts from 1)
  - `pageSize` (query, optional; integer; default: `10`; min: 1; max: 100; example: `10`) — Number of records per page
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/thinkSound/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — ThinkSound records retrieved successfully
  - `400` — Bad Request - Invalid pagination parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/thinkSound/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1ThinkSoundBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/thinkSound/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

### Post Processing
#### Caption Removal

##### POST /api/v1/userCaptionRemoval/start — Start caption removal task
Start a new caption removal task with video source URL Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserCaptionRemovalStart`
- JSON body fields:
  - `name` (body, required; string; example: `Remove captions from video`) — Name of the caption removal task
  - `source_url` (body, required; string; example: `https://example.com/video.mp4`) — URL of the source video
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userCaptionRemoval/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "Remove captions from video",
  "source_url": "https://example.com/video.mp4",
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Caption removal task started successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userCaptionRemoval/allRecords — Get all task records
Retrieve paginated list of user's tasks Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserCaptionRemovalAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userCaptionRemoval/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userCaptionRemoval/allProcessing — List processing records
allProcessing - HTTP GET Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserCaptionRemovalAllProcessing`
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userCaptionRemoval/allProcessing" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userCaptionRemoval/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserCaptionRemovalBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userCaptionRemoval/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userCaptionRemoval/{_id} — Get task details
Retrieve detailed information about a specific task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserCaptionRemovalId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userCaptionRemoval/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userCaptionRemoval/{_id} — Delete caption removal task
Delete a specific caption removal task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserCaptionRemovalId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — ID of the caption removal task
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userCaptionRemoval/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `400` — Bad Request - Invalid task ID
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userCaptionRemoval/retry — Retry a failed task
retry - HTTP POST Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserCaptionRemovalRetry`
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userCaptionRemoval/retry" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized - Invalid or missing JWT token
#### Upscale

##### POST /api/v1/userUpscale/start — Start upscale task
Start a new upscale task with image or video source URL Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserUpscaleStart`
- JSON body fields:
  - `name` (body, optional; string; example: `Upscale media`) — Name of the upscale task
  - `source_url` (body, required; string; example: `https://example.com/video.mp4`) — URL of the source image or video
  - `webhook_url` (body, optional; string; max length: 2048; example: `https://your-server.example.com/a2e/webhook`) — HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.
  - `webhook_token` (body, optional; string; max length: 256; example: `a-shared-secret`) — Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userUpscale/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "name": "Upscale media",
  "source_url": "https://example.com/video.mp4",
  "webhook_url": "https://your-server.example.com/a2e/webhook",
  "webhook_token": "a-shared-secret"
}
JSON
```
- Responses:
  - `200` — Successful response
  - `400` — Bad Request
  - `401` — Unauthorized

##### GET /api/v1/userUpscale/allRecords — Get all task records
Retrieve paginated list of user's tasks Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserUpscaleAllRecords`
- Request parameters:
  - `pageNum` (query, optional; integer; min: 1; example: `1`) — Page number
  - `pageSize` (query, optional; integer; example: `10`) — Page size
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userUpscale/allRecords?pageNum=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task list retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/userUpscale/batchDetail — Batch query task details
Query details for multiple tasks at once by providing an array of task IDs Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1UserUpscaleBatchDetail`
- JSON body fields:
  - `ids` (body, required; string[]; example: `["example"]`) — Array of task IDs to query
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/userUpscale/batchDetail" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "ids": [
    "example"
  ]
}
JSON
```
- Responses:
  - `200` — Batch details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### GET /api/v1/userUpscale/{_id} — Get task details
Retrieve detailed information about a specific task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1UserUpscaleId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/userUpscale/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task details retrieved successfully
  - `401` — Unauthorized - Invalid or missing JWT token

##### DELETE /api/v1/userUpscale/{_id} — Delete task
Delete a specific task Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `deleteApiV1UserUpscaleId`
- Request parameters:
  - `_id` (path, required; string; example: `507f1f77bcf86cd799439011`) — Task ID to delete
- Example request:
```bash
curl -X DELETE "https://cheap.dev/api/v1/userUpscale/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Task deleted successfully
  - `401` — Unauthorized - Invalid or missing JWT token

### Utilities
#### Miscellaneous

##### POST /api/v1/r2/get_upload_presigned_url — Get pre-signed upload URL
Legacy endpoint for generating a pre-signed R2 PUT URL. Prefer /api/v1/r2/upload-presigned-url for new integrations. If bucket is omitted, files are uploaded to 3days-apac by default. The returned key is automatically scoped to adam2eve/{env}/user/{user_id}/. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1R2GetUploadPresignedUrl`
- JSON body fields:
  - `key` (body, required; string; example: `example_key`) — key parameter
  - `bucket` (body, optional; string; example: `3days-apac`) — R2 bucket. Defaults to 3days-apac.
  - `expiresIn` (body, optional; integer; min: 60; example: `60`) — expiresIn parameter
  - `contentType` (body, optional; string; example: `image/png`) — MIME type to bind to the upload request.
  - `fileSize` (body, optional; number; example: `1048576`) — Optional file size in bytes. When provided, the pre-signed URL binds Content-Length.
  - `contentLength` (body, optional; number; example: `1048576`) — Optional Content-Length in bytes. Takes priority over fileSize if both are provided.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/r2/get_upload_presigned_url" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "key": "example_key",
  "bucket": "3days-apac",
  "expiresIn": 60,
  "contentType": "image/png",
  "fileSize": 1048576,
  "contentLength": 1048576
}
JSON
```
- Responses:
  - `200` — Item retrieved successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token

##### POST /api/v1/r2/upload-presigned-url — Get pre-signed upload URL
Generate a pre-signed R2 PUT URL for direct browser/client upload. If bucket is omitted, files are uploaded to 3days-apac by default. The returned key is automatically scoped to adam2eve/{env}/user/{user_id}/. Use cdnUrl as the public file URL after the PUT upload succeeds. API-token calls are charged using the R2 pricing rule; normal logged-in web/app calls are free. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `postApiV1R2UploadPresignedUrl`
- JSON body fields:
  - `key` (body, required; string; example: `example_key`) — key parameter
  - `bucket` (body, optional; string; example: `3days-apac`) — R2 bucket. Defaults to 3days-apac.
  - `expiresIn` (body, optional; integer; min: 60; example: `60`) — expiresIn parameter
  - `contentType` (body, optional; string; example: `image/png`) — MIME type to bind to the upload request.
  - `fileSize` (body, optional; number; example: `1048576`) — Optional file size in bytes. When provided, the pre-signed URL binds Content-Length.
  - `contentLength` (body, optional; number; example: `1048576`) — Optional Content-Length in bytes. Takes priority over fileSize if both are provided.
- Example request:
```bash
curl -X POST "https://cheap.dev/api/v1/r2/upload-presigned-url" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-binary @- <<'JSON'
{
  "key": "example_key",
  "bucket": "3days-apac",
  "expiresIn": 60,
  "contentType": "image/png",
  "fileSize": 1048576,
  "contentLength": 1048576
}
JSON
```
- Responses:
  - `200` — Operation completed successfully
  - `400` — Bad Request - Invalid parameters
  - `401` — Unauthorized - Invalid or missing JWT token
#### Credits

##### GET /api/v1/transactionRecord/creditsHistory — Get credits history
Retrieve paginated credits transaction history for the authenticated user. Positive amounts are credit grants or purchases; negative amounts are credit consumption. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
- Operation ID: `getApiV1TransactionRecordCreditsHistory`
- Request parameters:
  - `pageNum` (query, optional; integer; default: `1`; min: 1; example: `1`) — Page number, starting from 1.
  - `pageSize` (query, optional; integer; default: `10`; min: 1; example: `10`) — Number of records per page.
  - `is_consumption` (query, optional; boolean; example: `false`) — When true, only returns consumption records; when false, only returns credit income records.
- Example request:
```bash
curl -X GET "https://cheap.dev/api/v1/transactionRecord/creditsHistory?pageNum=1&pageSize=10&is_consumption=false" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```
- Responses:
  - `200` — Credits history retrieved successfully
  - `400` — Bad Request - Invalid query parameters
  - `401` — Unauthorized - Invalid or missing token