> ## Documentation Index > Fetch the complete documentation index at: https://docs.smartlyq.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi.json post /videos/generate openapi: 3.1.0 info: title: SmartlyQ API version: 1.0.0 description: > # SmartlyQ API REST API for the SmartlyQ platform: generate content, manage social posts, chatbots, media, and more. ## Quick Start 1. Get an API key from [app.smartlyq.com/my/developer](https://app.smartlyq.com/my/developer). 2. Send your first request: ```bash curl -H "Authorization: Bearer YOUR_API_KEY" https://api.smartlyq.com/v1/me ``` ## Authentication All requests (except health/docs) require a **Bearer token**. Use your API key as the token: - **Key types:** `sqk_live_*` (live) or `sqk_test_*` (test/sandbox). - **Header:** `Authorization: Bearer sqk_live_xxxx` or `Authorization: Bearer sqk_test_xxxx`. | Scope | Description | |-------|-------------| | `articles:read` | List and get articles | | `articles:write` | Generate, delete articles | | `images:read` | List and get images | | `images:write` | Generate, delete images | | `videos:read` | List and get videos | | `videos:write` | Generate, delete videos | | `social:read` | List accounts and posts | | `social:write` | Create, update, delete posts | | `audio:read` | Get audio resources | | `audio:write` | Text-to-speech, speech-to-text | | `urls:read` | List and get short URLs and stats | | `urls:write` | Shorten, delete URLs | | `captain:use` | AI Captain messages and conversations | | `chatbot:use` | Chatbots, train, messages, conversations | | `media:read` | List and get media | | `media:write` | Upload, delete media | | `analytics:read` | Overview, posts, account analytics | | `jobs:read` | List and get async jobs, cancel | | `seo:read` | Keyword research, SERP, rank tracking, competitors, backlinks, on-page audits | ## Billing & Credits - **Prepaid wallet:** API usage is deducted from your Developer API wallet (credits in SQC). - **Pricing:** See the [pricing table](https://smartlyq.com/pricing) and in-app Developer dashboard for per-operation costs. - **How it works:** Each billable request (e.g. generate, post, chatbot message) consumes credits; response may include `usage` with `cost` and `balance_remaining`. - **Top up:** Add credits via [app.smartlyq.com/my/developer](https://app.smartlyq.com/my/developer) (wallet / top-up). ## Rate Limiting Limits apply per API key (and may be enforced per user or IP). Default is 60 requests per minute per key (overridable per key). Response headers: | Header | Description | |--------|-------------| | `X-RateLimit-Limit` | Max requests per window | | `X-RateLimit-Remaining` | Remaining in current window | | `X-RateLimit-Reset` | Unix timestamp when the window resets | When exceeded: HTTP `429` with `Retry-After` header. ## Errors Errors are JSON with a consistent shape: ```json { "success": false, "error": { "code": "ERROR_CODE", "message": "Human-readable message", "details": {} }, "meta": { "request_id": "...", "timestamp": "..." } } ``` | HTTP | Code | Meaning | |-----|------|---------| | 400 | `BAD_REQUEST` | Malformed or invalid request | | 401 | `UNAUTHORIZED` | Missing or invalid API key | | 402 | `INSUFFICIENT_BALANCE` | Not enough credits | | 403 | `FORBIDDEN` | Valid key but insufficient scope or access | | 404 | `RESOURCE_NOT_FOUND` | Resource does not exist | | 409 | `CONFLICT` | Conflict (e.g. duplicate idempotency) | | 422 | `VALIDATION_ERROR` | Validation failed (fields in details) | | 429 | `RATE_LIMIT_EXCEEDED` | Too many requests | | 500 | `INTERNAL_ERROR` | Server error | ## Async Jobs & Polling Some operations (e.g. article or video generation) return **HTTP 202 Accepted** with a `job_id`. Poll for status: - **Poll:** `GET /jobs/{job_id}` until `status` is `completed`, `failed`, or `cancelled`. - Response includes `result` or `error` when finished. ## Webhooks Configure webhook URLs in the Developer dashboard. We send HTTP POST to your URL with a signed payload. - **Verification:** Validate signature using your webhook secret (see dashboard). - **Events:** e.g. `job.completed`, `job.failed`, `chatbot.conversation.ended`. ## Idempotency For POST/PUT/PATCH, send **`X-Idempotency-Key`** (unique value per logical operation). Within 24 hours, the same key returns the same response without re-executing. ## Pagination - **Offset:** `page` (1-based) and `per_page` (default 20, max 100). - Response includes `pagination` with `page`, `per_page`, `total`, `pages`. ## Versioning Current version is **v1**. Base path: `https://api.smartlyq.com/v1`. Future versions will use new path prefixes (e.g. `/v2/`). contact: name: SmartlyQ Support url: https://smartlyq.com email: support@smartlyq.com license: name: Proprietary url: https://smartlyq.com/terms servers: - url: https://api.smartlyq.com/v1 description: Production security: - BearerAuth: [] tags: - name: Articles description: Long-form article generation and management - name: Images description: AI image generation and listing - name: Videos description: AI video generation and listing - name: Social description: Social accounts and post scheduling - name: Content description: Content rewriting - name: Audio description: Text-to-speech and speech-to-text - name: URLs description: URL shortening and analytics - name: AI Captain description: AI Captain conversations - name: Chatbot description: Chatbots, training, and conversations - name: Media description: Media library and uploads - name: Analytics description: Analytics overview and reports - name: Jobs description: Async job status and cancellation - name: SEO description: >- DataForSEO-backed keyword research, SERP, rank tracking, competitors, backlinks and on-page audits - name: Account description: Current user, usage, and balance - name: Comments description: Comments endpoints - name: Direct Messages description: Direct Messages endpoints - name: Webhooks description: Subscribe to event notifications (HMAC-signed deliveries with retries). paths: /videos/generate: post: tags: - Videos summary: Generate video description: >- 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. operationId: generateVideo requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VideoGenerateRequest' examples: text_to_video: summary: Text-to-video (Kling v2.1) value: 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' image_to_video: summary: Image-to-video (Pixverse v4.5) value: model: pixverse-v4-5 type: image_to_video image_url: https://example.com/my-image.jpg prompt: Camera slowly pulls back to reveal the full scene duration: 5 resolution: 1080p style: Anime responses: '202': description: Accepted — poll GET /v1/jobs/{job_uid} for result content: application/json: schema: $ref: '#/components/schemas/VideoJobCreatedResponse' example: success: true data: job_uid: job_a1b2c3d4e5f6 status: queued usage: units: 1 cost: '0.2800' balance_remaining: '14.7200' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/InsufficientBalance' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' components: schemas: VideoGenerateRequest: type: object required: - model - type properties: model: type: string description: Model identifier. See GET /v1/videos/models for available values. example: kling-v2-1 type: type: string enum: - text_to_video - image_to_video description: >- Generation mode. `text_to_video` requires `prompt`. `image_to_video` requires `image_url`; `prompt` is optional motion guidance. example: text_to_video prompt: type: string description: >- 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: type: string format: uri description: >- Source image URL for image_to_video. Must be a publicly accessible JPEG or PNG. example: https://example.com/my-image.jpg duration: type: integer description: >- Video length in seconds. Valid values vary per model — see duration in /v1/videos/models. Defaults to the shortest valid duration. example: 10 resolution: type: string description: >- Output resolution (e.g. 720p, 1080p). Valid values vary per model — see resolution in /v1/videos/models. example: 1080p mode: type: string description: >- Generation quality mode (e.g. Standard, Professional, Fast). Valid values vary per model — see mode in /v1/videos/models. example: Professional aspect_ratio: type: string description: >- 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: type: string description: >- Visual style preset (e.g. Anime, Cyberpunk). Only supported by some models — see style in /v1/videos/models. example: Anime movement: type: string description: >- Camera/subject movement amplitude (Auto, Small, Medium, Large). Only supported by some models — see movement in /v1/videos/models. example: Medium negative_prompt: type: string description: >- 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: type: integer description: >- Reproducibility seed. Only supported by some models — see supports_seed in /v1/videos/models. example: 42 generate_audio: type: boolean description: >- Generate ambient audio alongside the video. Only supported by some models — see supports_generate_audio in /v1/videos/models. example: false camera_fixed: type: boolean description: >- Lock the camera position (no camera movement). Only supported by some models — see supports_camera_fixed in /v1/videos/models. example: false VideoJobCreatedResponse: type: object properties: success: type: boolean enum: - true data: type: object properties: job_uid: type: string description: Use with GET /v1/jobs/{job_uid} to poll for status. example: job_a1b2c3d4e5f6 status: type: string enum: - queued usage: $ref: '#/components/schemas/UsageMeta' meta: $ref: '#/components/schemas/RequestMeta' UsageMeta: type: object properties: units: type: integer cost: type: string example: '0.0150' balance_remaining: type: string example: '99.9850' RequestMeta: type: object properties: request_id: type: string timestamp: type: string format: date-time ErrorResponse: type: object properties: success: type: boolean enum: - false error: type: object properties: code: type: string message: type: string details: type: object meta: $ref: '#/components/schemas/RequestMeta' responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InsufficientBalance: description: Insufficient credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: Forbidden (scope or access) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ValidationError: description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' RateLimited: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: sqk_live_* or sqk_test_* description: API key from Developer dashboard (Bearer token). ````