Videos

Generate video

Submits a video generation request. Returns 202 Accepted immediately with a job_uid; poll GET /v1/jobs/{job_uid} for status and the final video URL.

Before submitting: call GET /v1/videos/models to retrieve the valid parameter values (duration, resolution, mode, aspect_ratio, etc.) for your chosen model. Passing an unsupported value returns a 422 validation error.

Billing: the cost is deducted from your API wallet when the job is accepted. If video generation fails on the provider side the charge is automatically refunded. Requires scope videos:write.

POST

videos

generate

curl --request POST \
  --url https://api.smartlyq.com/v1/videos/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "kling-v2-1",
  "type": "text_to_video",
  "prompt": "A lone astronaut walks across a crimson desert at sunset",
  "duration": 10,
  "mode": "Professional",
  "aspect_ratio": "16:9"
}
'

{
  "success": true,
  "data": {
    "job_uid": "job_a1b2c3d4e5f6",
    "status": "queued"
  },
  "usage": {
    "units": 1,
    "cost": "0.2800",
    "balance_remaining": "14.7200"
  }
}

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request body is not valid JSON.",
    "details": {}
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing or malformed Authorization header",
    "details": {}
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Wallet balance is insufficient for this request",
    "details": {
      "required": "0.0250",
      "balance": "0.0100"
    }
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "API key lacks required scope: social:write",
    "details": {
      "required_scope": "social:write"
    }
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required fields: content, platforms.",
    "details": {
      "fields": [
        "content",
        "platforms"
      ]
    }
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "details": {
      "retry_after": 12
    }
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "SERVER_ERROR",
    "message": "Something went wrong on our side. Retry with the same request_id - it is safe.",
    "details": {}
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

Authorizations

Authorization

string

header

required

API key from Developer dashboard (Bearer token).

Body

application/json

model

string

required

Model identifier. See GET /v1/videos/models for available values.

Example:

"kling-v2-1"

type

enum<string>

required

Generation mode. text_to_video requires prompt. image_to_video requires image_url; prompt is optional motion guidance.

Available options:

text_to_video,

image_to_video

Example:

"text_to_video"

prompt

string

Text description of the video. Required for text_to_video. Optional for image_to_video. Max length varies per model — see prompt_max_length in /v1/videos/models.

Example:

"A lone astronaut walks across a crimson desert at sunset"

image_url

string<uri>

Source image URL for image_to_video. Must be a publicly accessible JPEG or PNG.

Example:

"https://example.com/my-image.jpg"

duration

integer

Video length in seconds. Valid values vary per model — see duration in /v1/videos/models. Defaults to the shortest valid duration.

Example:

10

resolution

string

Output resolution (e.g. 720p, 1080p). Valid values vary per model — see resolution in /v1/videos/models.

Example:

"1080p"

mode

string

Generation quality mode (e.g. Standard, Professional, Fast). Valid values vary per model — see mode in /v1/videos/models.

Example:

"Professional"

aspect_ratio

string

Output aspect ratio (e.g. 16:9, 9:16, 1:1). Valid values vary per model — see aspect_ratio in /v1/videos/models.

Example:

"16:9"

style

string

Visual style preset (e.g. Anime, Cyberpunk). Only supported by some models — see style in /v1/videos/models.

Example:

"Anime"

movement

string

Camera/subject movement amplitude (Auto, Small, Medium, Large). Only supported by some models — see movement in /v1/videos/models.

Example:

"Medium"

negative_prompt

string

Elements to suppress in the output. Only supported by some models — see supports_negative_prompt in /v1/videos/models.

Example:

"blurry, low quality, watermark"

seed

integer

Reproducibility seed. Only supported by some models — see supports_seed in /v1/videos/models.

Example:

42

generate_audio

boolean

Generate ambient audio alongside the video. Only supported by some models — see supports_generate_audio in /v1/videos/models.

Example:

false

camera_fixed

boolean

Lock the camera position (no camera movement). Only supported by some models — see supports_camera_fixed in /v1/videos/models.

Example:

false

Response

Accepted — poll GET /v1/jobs/{job_uid} for result

success

enum<boolean>

Available options:

true

data

object

Show child attributes

usage

object

Show child attributes

meta

object

Show child attributes

curl --request POST \
  --url https://api.smartlyq.com/v1/videos/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "kling-v2-1",
  "type": "text_to_video",
  "prompt": "A lone astronaut walks across a crimson desert at sunset",
  "duration": 10,
  "mode": "Professional",
  "aspect_ratio": "16:9"
}
'

{
  "success": true,
  "data": {
    "job_uid": "job_a1b2c3d4e5f6",
    "status": "queued"
  },
  "usage": {
    "units": 1,
    "cost": "0.2800",
    "balance_remaining": "14.7200"
  }
}

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request body is not valid JSON.",
    "details": {}
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Missing or malformed Authorization header",
    "details": {}
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Wallet balance is insufficient for this request",
    "details": {
      "required": "0.0250",
      "balance": "0.0100"
    }
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "API key lacks required scope: social:write",
    "details": {
      "required_scope": "social:write"
    }
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required fields: content, platforms.",
    "details": {
      "fields": [
        "content",
        "platforms"
      ]
    }
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "details": {
      "retry_after": 12
    }
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

{
  "success": false,
  "error": {
    "code": "SERVER_ERROR",
    "message": "Something went wrong on our side. Retry with the same request_id - it is safe.",
    "details": {}
  },
  "meta": {
    "request_id": "req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34",
    "timestamp": "2026-07-26T09:41:22Z"
  }
}

Core

CRM

Profiles

AI Generation

Social

Ads

WhatsApp

Inbox

AI Assistants

Generate video

Authorizations

Body

Response