REST API v1

API Reference

Integrate Kling3Cheap into your applications. Generate images & videos, check balances, and monitor generation status — all via simple REST endpoints.

Authentication

All API requests must include your API key in the Authorization header as a Bearer token. Generate an API key from your Studio dashboard.

Authorization Header

Authorization: Bearer mcai_your_api_key_here

⚠ Keep your API key secret. Do not expose it in client-side code or public repositories. The full key is shown only once when generated.

Base URL

https://kling3cheap.com/api

All endpoints below are relative to this base URL.

Balance

Check Balance

GET/hp

Returns your current HP (credit) balance, daily check-in status, and streak.

Response

200 OK

{
  "freeHp": 100,
  "paidHp": 50,
  "totalHp": 150,
  "checkedInToday": true,
  "streak": 5
}

Parameter	Type	Required	Description
freeHp	number	Optional	Free HP credits available
paidHp	number	Optional	Paid HP credits available
totalHp	number	Optional	Total HP (freeHp + paidHp)
checkedInToday	boolean	Optional	Whether the daily check-in has been claimed today
streak	number	Optional	Current consecutive check-in streak (days)

Images

Generate Image

POST/generate/image

Submit a new image generation request. HP is deducted immediately and the request enters the processing queue. Parameters differ per model — see each model section below.

Common Parameters (all models)

Parameter	Type	Required	Description
modelId	string	Required	"nano-banana-pro", "nano-banana-2", "byteplus-seedream-4.5", "kling-3-omni"
speed	string	Required	"slow" (0.5× cost), "normal" (1× cost), "priority" (2× cost)

nano-banana-proNano Banana Pro

Parameter	Type	Required	Description
prompt	string	Required	Text prompt describing the desired image
resolution	string	Required	"1K", "2K", or "4K"
aspectRatio	string	Optional	"16:9", "9:16", "1:1", "2:3", "3:2", "3:4", or "4:3" (default: "1:1")
imageCount	number	Optional	Number of images to generate (default: 1)
autoEnhance	boolean	Optional	Auto-enhance the prompt (default: false)
visualRefs	array	Optional	Reference images for guided generation: [{ id, label, name, imageUrl, url, type }]

nano-banana-2Nano Banana 2

Parameter	Type	Required	Description
prompt	string	Required	Text prompt describing the desired image
resolution	string	Required	"1K", "2K", or "4K"
aspectRatio	string	Optional	"16:9", "9:16", "1:1", "2:3", "3:2", "3:4", or "4:3" (default: "1:1")
imageCount	number	Optional	Number of images to generate (default: 1)
autoEnhance	boolean	Optional	Auto-enhance the prompt (default: false)
visualRefs	array	Optional	Reference images for guided generation: [{ id, label, name, imageUrl, url, type }]

byteplus-seedream-4.5Byteplus Seedream 4.5

Parameter	Type	Required	Description
prompt	string	Required	Text prompt describing the desired image
resolution	string	Required	"1K", "2K", or "4K"
aspectRatio	string	Optional	"16:9", "9:16", "1:1", "2:3", "3:2", "3:4", or "4:3" (default: "1:1")
imageCount	number	Optional	Number of images to generate (default: 1)
autoEnhance	boolean	Optional	Auto-enhance the prompt (default: false)
visualRefs	array	Optional	Reference images for guided generation: [{ id, label, name, imageUrl, url, type }]

kling-3-omniKling 3 Omni

Parameter	Type	Required	Description
prompt	string	Required	Text prompt describing the desired image
resolution	string	Required	"1k", "2k", or "4k" (lowercase)
aspectRatio	string	Optional	"16:9", "9:16", "1:1", "2:3", "3:2", "3:4", or "4:3" (default: "1:1")
imageCount	number	Optional	Number of images to generate (default: 1)
autoEnhance	boolean	Optional	Auto-enhance the prompt (default: false)
visualRefs	array	Optional	Reference images for guided generation: [{ id, label, name, imageUrl, url, type }]

⚠ Note: Resolution values are lowercase for this model — use "1k", "2k", "4k".

Example Request

curl

curl -X POST https://kling3cheap.com/api/generate/image \
  -H "Authorization: Bearer mcai_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A cyberpunk cityscape at sunset",
    "modelId": "nano-banana-pro",
    "resolution": "2K",
    "speed": "normal",
    "aspectRatio": "16:9",
    "imageCount": 2
  }'

Response

200 OK

{
  "requestId": 42,
  "hpCost": 8,
  "hpBalance": {
    "freeHp": 92,
    "paidHp": 50,
    "totalHp": 142
  }
}

HP Cost Formula: baseCost × resolutionMultiplier × speedMultiplier × imageCount

Concurrent Limit: Max 4 pending/processing image requests at a time.

List Image Generations

GET/generations

Retrieve a paginated list of your image generation requests. Use this to check status and results.

Query Parameters

Parameter	Type	Required	Description
limit	number	Optional	Number of results (default: 50, max: 100)
offset	number	Optional	Number of results to skip (default: 0)
sort	string	Optional	"recent" (default) or "oldest"

Example Request

curl

curl "https://kling3cheap.com/api/generations?limit=10&sort=recent" \
  -H "Authorization: Bearer mcai_your_key"

Response

200 OK

{
  "generations": [
    {
      "id": 42,
      "modelId": "nano-banana-pro",
      "prompt": "A cyberpunk cityscape at sunset",
      "aspectRatio": "16:9",
      "resolution": "2K",
      "imageCount": 2,
      "speed": "normal",
      "autoEnhance": false,
      "hpCost": 8,
      "status": "success",
      "resultImages": [
        { "url": "https://...", "thumbnailUrl": "https://..." }
      ],
      "errorMessage": null,
      "createdAt": "2026-03-10T03:00:00.000Z"
    }
  ],
  "total": 1
}

Status Values

pending

processing

success

failed

Get Image Generation by ID

GET/generations/:id

Retrieve a single image generation request by its ID. Returns the full generation object including status, results, and metadata.

Path Parameters

Parameter	Type	Required	Description
id	number	Required	The generation request ID (returned from the generate endpoint)

Example Request

curl

curl "https://kling3cheap.com/api/generations/42" \
  -H "Authorization: Bearer mcai_your_key"

Response

200 OK

{
  "id": 42,
  "modelId": "nano-banana-pro",
  "prompt": "A cyberpunk cityscape at sunset",
  "aspectRatio": "16:9",
  "resolution": "2K",
  "imageCount": 2,
  "speed": "normal",
  "autoEnhance": false,
  "hpCost": 8,
  "status": "success",
  "resultImages": [
    { "url": "https://...", "thumbnailUrl": "https://..." },
    { "url": "https://...", "thumbnailUrl": "https://..." }
  ],
  "errorMessage": null,
  "isFavorite": false,
  "createdAt": "2026-03-10T03:00:00.000Z"
}

404 Not Found

{
  "error": "Not found"
}

Videos

Generate Video

POST/generate/video

Submit a new video generation request. HP is deducted immediately and the request enters the processing queue. Parameters differ per model — see each model section below.

Common Parameters (all models)

Parameter	Type	Required	Description
modelId	string	Required	"kling-3", "kling-2.6", "veo-3.1", "byte-plus-seedance-1-5"
speed	string	Required	"slow" (0.5× cost), "normal" (1× cost), "priority" (2× cost)

kling-3Kling 3

Parameter	Type	Required	Description
prompt	string	Required	Text prompt (required unless startFrame or endFrame is provided)
resolution	string	Required	"std(720p)" or "pro(1080p)"
duration	number	Required	Duration in seconds (3–15)
aspectRatio	string	Optional	"16:9", "9:16", or "1:1" (default: "16:9")
autoEnhance	boolean	Optional	Auto-enhance the prompt (default: false)
generateAudio	boolean	Optional	Generate sound for the video (default: false, 1.5× cost)
multiShot	boolean	Optional	Enable multi-shot mode (default: false)
startFrame	object \| null	Optional	Start keyframe image: { id, label, url, type }
endFrame	object \| null	Optional	End keyframe image: { id, label, url, type }

kling-2.6Kling 2.6

Parameter	Type	Required	Description
prompt	string	Required	Text prompt (required unless startFrame or endFrame is provided)
resolution	string	Required	"std(720p)" or "pro(1080p)"
duration	number	Required	Duration in seconds — 5 or 10
aspectRatio	string	Optional	"16:9", "9:16", or "1:1" (default: "16:9")
autoEnhance	boolean	Optional	Auto-enhance the prompt (default: false)
generateAudio	boolean	Optional	Generate sound (default: false, 1.5× cost). Mutually exclusive with endFrame.
startFrame	object \| null	Optional	Start keyframe image: { id, label, url, type }
endFrame	object \| null	Optional	End keyframe image: { id, label, url, type }. Mutually exclusive with generateAudio.

ℹ️ Note: End frame and audio generation are mutually exclusive. If endFrame is provided, audio will not be generated, and vice versa.

veo-3.1Veo 3.1

Parameter	Type	Required	Description
prompt	string	Required	Text prompt describing the desired video
resolution	string	Required	"720p", "1080p", or "4K"
duration	number	Required	Duration in seconds — 4, 6, or 8
aspectRatio	string	Optional	"16:9" or "9:16" (default: "16:9")
generateAudio	boolean	Optional	Generate audio for the video (default: false, 1.5× cost)
startFrame	object \| null	Optional	Start keyframe image: { id, label, url, type }
endFrame	object \| null	Optional	End keyframe image: { id, label, url, type }

byte-plus-seedance-1-5Seedance 1.5

Parameter	Type	Required	Description
prompt	string	Required	Text prompt (required unless startFrame or endFrame is provided)
resolution	string	Required	"720p" or "1080p"
duration	number	Required	Duration in seconds (4–12)
aspectRatio	string	Optional	"16:9", "9:16", "1:1", or "21:9" (default: "16:9")
generateAudio	boolean	Optional	Generate sound for the video (default: false, 1.5× cost)
startFrame	object \| null	Optional	Start keyframe image: { id, label, url, type }
endFrame	object \| null	Optional	End keyframe image: { id, label, url, type }

Example Request

curl

curl -X POST https://kling3cheap.com/api/generate/video \
  -H "Authorization: Bearer mcai_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A drone shot flying over a mountain valley",
    "modelId": "kling-3",
    "resolution": "pro(1080p)",
    "duration": 5,
    "speed": "normal",
    "generateAudio": true
  }'

Response

200 OK

{
  "requestId": 18,
  "hpCost": 56,
  "hpBalance": {
    "freeHp": 44,
    "paidHp": 50,
    "totalHp": 94
  }
}

HP Cost Formula: baseCost × duration × resolutionMultiplier × speedMultiplier × audioMultiplier

Concurrent Limit: Max 2 pending/processing video requests at a time.

Generate Motion Control Video

POST/generate/motion-control

Generate a video by applying motion from a reference video to a character image.

Request Body

Parameter	Type	Required	Description
characterUrl	string	Required	URL of the character image to animate
referenceUrl	string	Required	URL of the motion reference video
videoMode	string	Required	"std" (720p) or "pro" (1080p)
speed	string	Required	"slow", "normal", or "priority"
duration	number	Required	Duration in seconds (1–30)
prompt	string	Optional	Optional text prompt for guidance
keepOriginalSound	boolean	Optional	Keep reference audio (default: true)

Example Request

curl

curl -X POST https://kling3cheap.com/api/generate/motion-control \
  -H "Authorization: Bearer mcai_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "characterUrl": "https://example.com/character.png",
    "referenceUrl": "https://example.com/dance_ref.mp4",
    "videoMode": "pro",
    "speed": "normal",
    "duration": 10
  }'

Response

200 OK

{
  "requestId": 19,
  "hpCost": 150,
  "hpBalance": {
    "freeHp": 0,
    "paidHp": 0,
    "totalHp": 0
  }
}

List Video Generations

GET/video-generations

Retrieve a paginated list of your video generation requests (including motion control). Use this to check status and get result URLs.

Query Parameters

Parameter	Type	Required	Description
limit	number	Optional	Number of results (default: 50, max: 100)
offset	number	Optional	Number of results to skip (default: 0)
sort	string	Optional	"recent" (default) or "oldest"

Example Request

curl

curl "https://kling3cheap.com/api/video-generations?limit=5" \
  -H "Authorization: Bearer mcai_your_key"

Response

200 OK

{
  "generations": [
    {
      "id": 18,
      "modelId": "kling-3",
      "prompt": "A drone shot flying over a mountain valley",
      "aspectRatio": "16:9",
      "resolution": "pro(1080p)",
      "duration": 5,
      "speed": "normal",
      "generateAudio": true,
      "multiShot": false,
      "startFrame": null,
      "endFrame": null,
      "hpCost": 56,
      "status": "success",
      "resultVideoUrl": "https://...",
      "thumbnailUrl": "https://...",
      "errorMessage": null,
      "createdAt": "2026-03-10T03:00:00.000Z"
    }
  ],
  "total": 1
}

Status Values

pending

processing

success

failed

Get Video Generation by ID

GET/video-generations/:id

Retrieve a single video generation request by its ID. Returns the full generation object including status, result URL, and metadata.

Path Parameters

Parameter	Type	Required	Description
id	number	Required	The video generation request ID (returned from the generate endpoint)

Example Request

curl

curl "https://kling3cheap.com/api/video-generations/18" \
  -H "Authorization: Bearer mcai_your_key"

Response

200 OK

{
  "id": 18,
  "modelId": "kling-3",
  "prompt": "A drone shot flying over a mountain valley",
  "aspectRatio": "16:9",
  "resolution": "pro(1080p)",
  "duration": 5,
  "speed": "normal",
  "generateAudio": true,
  "multiShot": false,
  "startFrame": null,
  "endFrame": null,
  "hpCost": 56,
  "status": "processing",
  "resultVideoUrl": null,
  "thumbnailUrl": null,
  "errorMessage": null,
  "isFavorite": false,
  "createdAt": "2026-03-10T03:00:00.000Z"
}

404 Not Found

{
  "error": "Not found"
}

Uploads

Upload Image

POST/upload/image

Upload an image file. The uploaded image URL can be used as a visual reference for image generation, or as a start/end frame for video generation.

Request Body (multipart/form-data)

Parameter	Type	Required	Description
file	File	Required	Image file to upload (JPEG, PNG, WebP)

Example Request

curl

curl -X POST https://kling3cheap.com/api/upload/image \
  -H "Authorization: Bearer mcai_your_key" \
  -F "file=@photo.jpg"

Response

200 OK

{
  "id": 7,
  "imageUrl": "https://kling3cheap.com/media/uploads/abc123_raw.jpg",
  "width": 1920,
  "height": 1080
}

Parameter	Type	Required	Description
id	number	Optional	Upload record ID
imageUrl	string	Optional	Processed image URL (use this for generation requests)
width	number	Optional	Image width in pixels
height	number	Optional	Image height in pixels

Upload Video

POST/upload/video

Upload a video file. The returned CDN URL can be used as a motion reference for motion control video generation.

Request Body (multipart/form-data)

Parameter	Type	Required	Description
file	File	Required	Video file to upload (MP4)

Example Request

curl

curl -X POST https://kling3cheap.com/api/upload/video \
  -H "Authorization: Bearer mcai_your_key" \
  -F "file=@dance.mp4"

Response

200 OK

{
  "cdnUrl": "https://media.kling3cheap.com/video/action-video/xyz789.mp4"
}

Parameter	Type	Required	Description
cdnUrl	string	Optional	CDN URL of the uploaded video (use this as referenceUrl in motion control)

List Uploaded Images

GET/upload/image/list

Retrieve a paginated list of your previously uploaded images.

Query Parameters

Parameter	Type	Required	Description
limit	number	Optional	Number of results (default: 20, max: 100)
offset	number	Optional	Number of results to skip (default: 0)

Example Request

curl

curl "https://kling3cheap.com/api/upload/image/list?limit=10" \
  -H "Authorization: Bearer mcai_your_key"

Response

200 OK

{
  "images": [
    {
      "id": 7,
      "imageUrl": "https://media.kling3cheap.com/uploads/abc123_raw.jpg",
      "width": 1920,
      "height": 1080,
      "createdAt": "2026-03-10T03:00:00.000Z"
    }
  ],
  "total": 1
}

Rate Limits

To ensure fair usage and system stability, each account has default concurrent generation limits. These limits apply to the number of pending or processing requests at any given time.

Resource	Default Limit	Description
Image Generation	4 concurrent	Max 4 pending/processing image generation requests at a time
Video Generation	2 concurrent	Max 2 pending/processing video generation requests at a time (includes motion control)

If you exceed the concurrent limit, the API will return a 429 Too Many Requests error. Wait for existing requests to complete before submitting new ones.

🚀 Need higher limits? If your use case requires more concurrent generations, reach out to discuss raising your account limits.

Errors

All errors follow a consistent JSON format with an error field.

Error Response

{
  "error": "Description of what went wrong"
}

Status	Meaning	Common Causes
400	Bad Request	Missing or invalid fields (prompt, modelId, speed, etc.)
401	Unauthorized	Missing or invalid API key / session
402	Payment Required	Insufficient HP for the requested generation
404	Not Found	Generation request not found or not owned by you
429	Too Many Requests	Concurrent generation limit reached (4 images / 2 videos)
500	Internal Error	Unexpected server error

Insufficient HP Response (402)

402 Payment Required

{
  "error": "Insufficient HP",
  "required": 56,
  "available": 20
}

Visit the Studio to manage your API keys.