diff --git a/01 Projects/cc-dashboard/CC Dashboard.md b/01 Projects/cc-dashboard/CC Dashboard.md index 925469a..70c114e 100644 --- a/01 Projects/cc-dashboard/CC Dashboard.md +++ b/01 Projects/cc-dashboard/CC Dashboard.md @@ -268,6 +268,7 @@ All endpoints except `/auth/login` require valid JWT in `Authorization: Bearer { ## Change Log | Date | Requested | Changed | Files | |------|-----------|---------|-------| +| 2026-05-06 | Fix undefined toFixed() | Add null check for toFixed() call, verify server deployment | ProjectsView-CZF7uexl.js, CardContent.vue | | 2026-05-06 | Fix Projects TypeError | Add null check before toFixed call | ProjectsView-CZF7uexl.js, CardContent.vue | | 2026-05-06 | Calendar view, Azure DevOps sync, task planner | Dashboard preset to 'today', Cache-Control header, Live Feed bug fixes | index.html, dashboard config, feed module | | 2026-05-06 | Calendar view with time tracking | Add calendar component, Azure DevOps integration, daily planner, Apache ProxyPass config, FastAPI root_path routes | main.py, Apache config | diff --git a/99 Daily/2026-05-06.md b/99 Daily/2026-05-06.md index a6d1a94..b57e5b9 100644 --- a/99 Daily/2026-05-06.md +++ b/99 Daily/2026-05-06.md @@ -134,3 +134,6 @@ tags: [daily] - 21:25 (2min) | `ai_leed` - **Asked:** Check if auto-update works for all Docker containers and LXC on homelab. - **Done:** Verified Watchtower configuration in CT102 and LXC auto-update settings on Proxmox host. +- 21:28 (1min) | `cc-dashboard` + - **Asked:** Asked | Fixed undefined toFixed() error in Projects view and verified live deployment + - **Done:** Done | Resolved TypeError by adding null check for toFixed() method and confirmed updated build is running on server diff --git a/raw/_processed/Agent SDK overview 1.md b/raw/_processed/Agent SDK overview 1.md deleted file mode 100644 index add7c28..0000000 --- a/raw/_processed/Agent SDK overview 1.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -title: "Agent SDK overview" -source: "https://code.claude.com/docs/en/agent-sdk/overview" -author: -published: -created: 2026-04-17 -description: "Build production AI agents with Claude Code as a library" -tags: - - "clippings" ---- -The Claude Code SDK has been renamed to the Claude Agent SDK. If you’re migrating from the old SDK, see the [Migration Guide](https://code.claude.com/docs/en/agent-sdk/migration-guide). - -Build AI agents that autonomously read files, run commands, search the web, edit code, and more. The Agent SDK gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript. - -Opus 4.7 (`claude-opus-4-7`) requires Agent SDK v0.2.111 or later. If you see a `thinking.type.enabled` API error, see [Troubleshooting](https://code.claude.com/docs/en/agent-sdk/quickstart#troubleshooting). - -```python -import asyncio -from claude_agent_sdk import query, ClaudeAgentOptions - -async def main(): - async for message in query( - prompt="Find and fix the bug in auth.py", - options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]), - ): - print(message) # Claude reads the file, finds the bug, edits it - -asyncio.run(main()) -``` - -The Agent SDK includes built-in tools for reading files, running commands, and editing code, so your agent can start working immediately without you implementing tool execution. Dive into the quickstart or explore real agents built with the SDK: - -## [Quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart) - -Build a bug-fixing agent in minutes - -## [Example agents](https://github.com/anthropics/claude-agent-sdk-demos) - -Email assistant, research agent, and more - -## Get started - -**Ready to build?** Follow the [Quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart) to create an agent that finds and fixes bugs in minutes. - -## Capabilities - -Everything that makes Claude Code powerful is available in the SDK: - -- Built-in tools -- Hooks -- Subagents -- MCP -- Permissions -- Sessions - -Your agent can read files, run commands, and search codebases out of the box. Key tools include: - -| Tool | What it does | -| --- | --- | -| **Read** | Read any file in the working directory | -| **Write** | Create new files | -| **Edit** | Make precise edits to existing files | -| **Bash** | Run terminal commands, scripts, git operations | -| **Monitor** | Watch a background script and react to each output line as an event | -| **Glob** | Find files by pattern (`**/*.ts`, `src/**/*.py`) | -| **Grep** | Search file contents with regex | -| **WebSearch** | Search the web for current information | -| **WebFetch** | Fetch and parse web page content | -| **[AskUserQuestion](https://code.claude.com/docs/en/agent-sdk/user-input#handle-clarifying-questions)** | Ask the user clarifying questions with multiple choice options | - -This example creates an agent that searches your codebase for TODO comments: - -```python -import asyncio -from claude_agent_sdk import query, ClaudeAgentOptions - -async def main(): - async for message in query( - prompt="Find all TODO comments and create a summary", - options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]), - ): - if hasattr(message, "result"): - print(message.result) - -asyncio.run(main()) -``` - -### Claude Code features - -The SDK also supports Claude Code’s filesystem-based configuration. With default options the SDK loads these from `.claude/` in your working directory and `~/.claude/`. To restrict which sources load, set `setting_sources` (Python) or `settingSources` (TypeScript) in your options. - -| Feature | Description | Location | -| --- | --- | --- | -| [Skills](https://code.claude.com/docs/en/agent-sdk/skills) | Specialized capabilities defined in Markdown | `.claude/skills/*/SKILL.md` | -| [Slash commands](https://code.claude.com/docs/en/agent-sdk/slash-commands) | Custom commands for common tasks | `.claude/commands/*.md` | -| [Memory](https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts) | Project context and instructions | `CLAUDE.md` or `.claude/CLAUDE.md` | -| [Plugins](https://code.claude.com/docs/en/agent-sdk/plugins) | Extend with custom commands, agents, and MCP servers | Programmatic via `plugins` option | - -## Compare the Agent SDK to other Claude tools - -The Claude Platform offers multiple ways to build with Claude. Here’s how the Agent SDK fits in: - -- Agent SDK vs Client SDK -- Agent SDK vs Claude Code CLI - -The [Anthropic Client SDK](https://platform.claude.com/docs/en/api/client-sdks) gives you direct API access: you send prompts and implement tool execution yourself. The **Agent SDK** gives you Claude with built-in tool execution. - -With the Client SDK, you implement a tool loop. With the Agent SDK, Claude handles it: - -```python -# Client SDK: You implement the tool loop -response = client.messages.create(...) -while response.stop_reason == "tool_use": - result = your_tool_executor(response.tool_use) - response = client.messages.create(tool_result=result, **params) - -# Agent SDK: Claude handles tools autonomously -async for message in query(prompt="Fix the bug in auth.py"): - print(message) -``` - -## Changelog - -View the full changelog for SDK updates, bug fixes, and new features: - -- **TypeScript SDK**: [view CHANGELOG.md](https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md) -- **Python SDK**: [view CHANGELOG.md](https://github.com/anthropics/claude-agent-sdk-python/blob/main/CHANGELOG.md) - -## Reporting bugs - -If you encounter bugs or issues with the Agent SDK: - -- **TypeScript SDK**: [report issues on GitHub](https://github.com/anthropics/claude-agent-sdk-typescript/issues) -- **Python SDK**: [report issues on GitHub](https://github.com/anthropics/claude-agent-sdk-python/issues) - -## Branding guidelines - -For partners integrating the Claude Agent SDK, use of Claude branding is optional. When referencing Claude in your product: - -**Allowed:** - -- “Claude Agent” (preferred for dropdown menus) -- “Claude” (when within a menu already labeled “Agents”) -- ” Powered by Claude” (if you have an existing agent name) - -**Not permitted:** - -- “Claude Code” or “Claude Code Agent” -- Claude Code-branded ASCII art or visual elements that mimic Claude Code - -Your product should maintain its own branding and not appear to be Claude Code or any Anthropic product. For questions about branding compliance, contact the Anthropic [sales team](https://www.anthropic.com/contact-sales). - -## License and terms - -Use of the Claude Agent SDK is governed by [Anthropic’s Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms), including when you use it to power products and services that you make available to your own customers and end users, except to the extent a specific component or dependency is covered by a different license as indicated in that component’s LICENSE file. - -## Next steps - -## [Quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart) - -Build an agent that finds and fixes bugs in minutes - -## [Example agents](https://github.com/anthropics/claude-agent-sdk-demos) - -Email assistant, research agent, and more - -## [TypeScript SDK](https://code.claude.com/docs/en/agent-sdk/typescript) - -Full TypeScript API reference and examples - -## [Python SDK](https://code.claude.com/docs/en/agent-sdk/python) - -Full Python API reference and examples \ No newline at end of file diff --git a/raw/_processed/Agent Skills in the SDK 1.md b/raw/_processed/Agent Skills in the SDK 1.md deleted file mode 100644 index a49fc8d..0000000 --- a/raw/_processed/Agent Skills in the SDK 1.md +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: "Agent Skills in the SDK" -source: "https://code.claude.com/docs/en/agent-sdk/plugins" -author: -published: -created: 2026-04-17 -description: "Extend Claude with specialized capabilities using Agent Skills in the Claude Agent SDK" -tags: - - "clippings" ---- -Plugins allow you to extend Claude Code with custom functionality that can be shared across projects. Through the Agent SDK, you can programmatically load plugins from local directories to add custom slash commands, agents, skills, hooks, and MCP servers to your agent sessions. - -## What are plugins? - -Plugins are packages of Claude Code extensions that can include: - -- **Skills**: Model-invoked capabilities that Claude uses autonomously (can also be invoked with `/skill-name`) -- **Agents**: Specialized subagents for specific tasks -- **Hooks**: Event handlers that respond to tool use and other events -- **MCP servers**: External tool integrations via Model Context Protocol - -The `commands/` directory is a legacy format. Use `skills/` for new plugins. Claude Code continues to support both formats for backward compatibility. - -For complete information on plugin structure and how to create plugins, see [Plugins](https://code.claude.com/docs/en/plugins). - -## Loading plugins - -Load plugins by providing their local file system paths in your options configuration. The SDK supports loading multiple plugins from different locations. - -```typescript -import { query } from "@anthropic-ai/claude-agent-sdk"; - -for await (const message of query({ - prompt: "Hello", - options: { - plugins: [ - { type: "local", path: "./my-plugin" }, - { type: "local", path: "/absolute/path/to/another-plugin" } - ] - } -})) { - // Plugin commands, agents, and other features are now available -} -``` - -### Path specifications - -Plugin paths can be: - -- **Relative paths**: Resolved relative to your current working directory (for example, `"./plugins/my-plugin"`) -- **Absolute paths**: Full file system paths (for example, `"/home/user/plugins/my-plugin"`) - -The path should point to the plugin’s root directory (the directory containing `.claude-plugin/plugin.json`). - -## Verifying plugin installation - -When plugins load successfully, they appear in the system initialization message. You can verify that your plugins are available: - -```typescript -import { query } from "@anthropic-ai/claude-agent-sdk"; - -for await (const message of query({ - prompt: "Hello", - options: { - plugins: [{ type: "local", path: "./my-plugin" }] - } -})) { - if (message.type === "system" && message.subtype === "init") { - // Check loaded plugins - console.log("Plugins:", message.plugins); - // Example: [{ name: "my-plugin", path: "./my-plugin" }] - - // Check available commands from plugins - console.log("Commands:", message.slash_commands); - // Example: ["/help", "/compact", "my-plugin:custom-command"] - } -} -``` - -## Using plugin skills - -Skills from plugins are automatically namespaced with the plugin name to avoid conflicts. When invoked as slash commands, the format is `plugin-name:skill-name`. - -```typescript -import { query } from "@anthropic-ai/claude-agent-sdk"; - -// Load a plugin with a custom /greet skill -for await (const message of query({ - prompt: "/my-plugin:greet", // Use plugin skill with namespace - options: { - plugins: [{ type: "local", path: "./my-plugin" }] - } -})) { - // Claude executes the custom greeting skill from the plugin - if (message.type === "assistant") { - console.log(message.message.content); - } -} -``` - -If you installed a plugin via the CLI (for example, `/plugin install my-plugin@marketplace`), you can still use it in the SDK by providing its installation path. Check `~/.claude/plugins/` for CLI-installed plugins. - -## Complete example - -Here’s a full example demonstrating plugin loading and usage: - -```typescript -import { query } from "@anthropic-ai/claude-agent-sdk"; -import * as path from "path"; - -async function runWithPlugin() { - const pluginPath = path.join(__dirname, "plugins", "my-plugin"); - - console.log("Loading plugin from:", pluginPath); - - for await (const message of query({ - prompt: "What custom commands do you have available?", - options: { - plugins: [{ type: "local", path: pluginPath }], - maxTurns: 3 - } - })) { - if (message.type === "system" && message.subtype === "init") { - console.log("Loaded plugins:", message.plugins); - console.log("Available commands:", message.slash_commands); - } - - if (message.type === "assistant") { - console.log("Assistant:", message.message.content); - } - } -} - -runWithPlugin().catch(console.error); -``` - -## Plugin structure reference - -A plugin directory must contain a `.claude-plugin/plugin.json` manifest file. It can optionally include: - -```text -my-plugin/ -├── .claude-plugin/ -│ └── plugin.json # Required: plugin manifest -├── skills/ # Agent Skills (invoked autonomously or via /skill-name) -│ └── my-skill/ -│ └── SKILL.md -├── commands/ # Legacy: use skills/ instead -│ └── custom-cmd.md -├── agents/ # Custom agents -│ └── specialist.md -├── hooks/ # Event handlers -│ └── hooks.json -└── .mcp.json # MCP server definitions -``` - -For detailed information on creating plugins, see: - -- [Plugins](https://code.claude.com/docs/en/plugins) - Complete plugin development guide -- [Plugins reference](https://code.claude.com/docs/en/plugins-reference) - Technical specifications and schemas - -## Common use cases - -### Development and testing - -Load plugins during development without installing them globally: - -```typescript -plugins: [{ type: "local", path: "./dev-plugins/my-plugin" }]; -``` - -### Project-specific extensions - -Include plugins in your project repository for team-wide consistency: - -```typescript -plugins: [{ type: "local", path: "./project-plugins/team-workflows" }]; -``` - -### Multiple plugin sources - -Combine plugins from different locations: - -```typescript -plugins: [ - { type: "local", path: "./local-plugin" }, - { type: "local", path: "~/.claude/custom-plugins/shared-plugin" } -]; -``` - -## Troubleshooting - -### Plugin not loading - -If your plugin doesn’t appear in the init message: - -1. **Check the path**: Ensure the path points to the plugin root directory (containing `.claude-plugin/`) -2. **Validate plugin.json**: Ensure your manifest file has valid JSON syntax -3. **Check file permissions**: Ensure the plugin directory is readable - -### Skills not appearing - -If plugin skills don’t work: - -1. **Use the namespace**: Plugin skills require the `plugin-name:skill-name` format when invoked as slash commands -2. **Check init message**: Verify the skill appears in `slash_commands` with the correct namespace -3. **Validate skill files**: Ensure each skill has a `SKILL.md` file in its own subdirectory under `skills/` (for example, `skills/my-skill/SKILL.md`) - -### Path resolution issues - -If relative paths don’t work: - -1. **Check working directory**: Relative paths are resolved from your current working directory -2. **Use absolute paths**: For reliability, consider using absolute paths -3. **Normalize paths**: Use path utilities to construct paths correctly - -## See also - -- [Plugins](https://code.claude.com/docs/en/plugins) - Complete plugin development guide -- [Plugins reference](https://code.claude.com/docs/en/plugins-reference) - Technical specifications -- [Slash Commands](https://code.claude.com/docs/en/agent-sdk/slash-commands) - Using slash commands in the SDK -- [Subagents](https://code.claude.com/docs/en/agent-sdk/subagents) - Working with specialized agents -- [Skills](https://code.claude.com/docs/en/agent-sdk/skills) - Using Agent Skills \ No newline at end of file diff --git a/raw/_processed/Agent Skills in the SDK.md b/raw/_processed/Agent Skills in the SDK.md index f94b953..94d104e 100644 --- a/raw/_processed/Agent Skills in the SDK.md +++ b/raw/_processed/Agent Skills in the SDK.md @@ -200,4 +200,151 @@ For general Skills troubleshooting (YAML syntax, debugging, etc.), see the [Clau - [Slash Commands in the SDK](https://code.claude.com/docs/en/agent-sdk/slash-commands): User-invoked commands - [SDK Overview](https://code.claude.com/docs/en/agent-sdk/overview): General SDK concepts - [TypeScript SDK Reference](https://code.claude.com/docs/en/agent-sdk/typescript): Complete API documentation -- [Python SDK Reference](https://code.claude.com/docs/en/agent-sdk/python): Complete API documentation \ No newline at end of file +- [Python SDK Reference](https://code.claude.com/docs/en/agent-sdk/python): Complete API documentation +source: "https://code.claude.com/docs/en/agent-sdk/plugins" +Plugins allow you to extend Claude Code with custom functionality that can be shared across projects. Through the Agent SDK, you can programmatically load plugins from local directories to add custom slash commands, agents, skills, hooks, and MCP servers to your agent sessions. +## What are plugins? +Plugins are packages of Claude Code extensions that can include: +- **Skills**: Model-invoked capabilities that Claude uses autonomously (can also be invoked with `/skill-name`) +- **Agents**: Specialized subagents for specific tasks +- **Hooks**: Event handlers that respond to tool use and other events +- **MCP servers**: External tool integrations via Model Context Protocol +The `commands/` directory is a legacy format. Use `skills/` for new plugins. Claude Code continues to support both formats for backward compatibility. +For complete information on plugin structure and how to create plugins, see [Plugins](https://code.claude.com/docs/en/plugins). +## Loading plugins +Load plugins by providing their local file system paths in your options configuration. The SDK supports loading multiple plugins from different locations. +```typescript +import { query } from "@anthropic-ai/claude-agent-sdk"; +for await (const message of query({ + prompt: "Hello", + options: { + plugins: [ + { type: "local", path: "./my-plugin" }, + { type: "local", path: "/absolute/path/to/another-plugin" } + ] + } +})) { + // Plugin commands, agents, and other features are now available +} +### Path specifications +Plugin paths can be: +- **Relative paths**: Resolved relative to your current working directory (for example, `"./plugins/my-plugin"`) +- **Absolute paths**: Full file system paths (for example, `"/home/user/plugins/my-plugin"`) +The path should point to the plugin’s root directory (the directory containing `.claude-plugin/plugin.json`). +## Verifying plugin installation +When plugins load successfully, they appear in the system initialization message. You can verify that your plugins are available: +```typescript +import { query } from "@anthropic-ai/claude-agent-sdk"; +for await (const message of query({ + prompt: "Hello", + options: { + plugins: [{ type: "local", path: "./my-plugin" }] + } +})) { + if (message.type === "system" && message.subtype === "init") { + // Check loaded plugins + console.log("Plugins:", message.plugins); + // Example: [{ name: "my-plugin", path: "./my-plugin" }] + // Check available commands from plugins + console.log("Commands:", message.slash_commands); + // Example: ["/help", "/compact", "my-plugin:custom-command"] + } +} +## Using plugin skills +Skills from plugins are automatically namespaced with the plugin name to avoid conflicts. When invoked as slash commands, the format is `plugin-name:skill-name`. +```typescript +import { query } from "@anthropic-ai/claude-agent-sdk"; +// Load a plugin with a custom /greet skill +for await (const message of query({ + prompt: "/my-plugin:greet", // Use plugin skill with namespace + options: { + plugins: [{ type: "local", path: "./my-plugin" }] + } +})) { + // Claude executes the custom greeting skill from the plugin + if (message.type === "assistant") { + console.log(message.message.content); + } +} +If you installed a plugin via the CLI (for example, `/plugin install my-plugin@marketplace`), you can still use it in the SDK by providing its installation path. Check `~/.claude/plugins/` for CLI-installed plugins. +## Complete example +Here’s a full example demonstrating plugin loading and usage: +```typescript +import { query } from "@anthropic-ai/claude-agent-sdk"; +import * as path from "path"; +async function runWithPlugin() { + const pluginPath = path.join(__dirname, "plugins", "my-plugin"); + console.log("Loading plugin from:", pluginPath); + for await (const message of query({ + prompt: "What custom commands do you have available?", + options: { + plugins: [{ type: "local", path: pluginPath }], + maxTurns: 3 + } + })) { + if (message.type === "system" && message.subtype === "init") { + console.log("Loaded plugins:", message.plugins); + console.log("Available commands:", message.slash_commands); + } + if (message.type === "assistant") { + console.log("Assistant:", message.message.content); + } + } +} +runWithPlugin().catch(console.error); +## Plugin structure reference +A plugin directory must contain a `.claude-plugin/plugin.json` manifest file. It can optionally include: +```text +my-plugin/ +├── .claude-plugin/ +│ └── plugin.json # Required: plugin manifest +├── skills/ # Agent Skills (invoked autonomously or via /skill-name) +│ └── my-skill/ +│ └── SKILL.md +├── commands/ # Legacy: use skills/ instead +│ └── custom-cmd.md +├── agents/ # Custom agents +│ └── specialist.md +├── hooks/ # Event handlers +│ └── hooks.json +└── .mcp.json # MCP server definitions +For detailed information on creating plugins, see: +- [Plugins](https://code.claude.com/docs/en/plugins) - Complete plugin development guide +- [Plugins reference](https://code.claude.com/docs/en/plugins-reference) - Technical specifications and schemas +## Common use cases +### Development and testing +Load plugins during development without installing them globally: +```typescript +plugins: [{ type: "local", path: "./dev-plugins/my-plugin" }]; +### Project-specific extensions +Include plugins in your project repository for team-wide consistency: +```typescript +plugins: [{ type: "local", path: "./project-plugins/team-workflows" }]; +### Multiple plugin sources +Combine plugins from different locations: +```typescript +plugins: [ + { type: "local", path: "./local-plugin" }, + { type: "local", path: "~/.claude/custom-plugins/shared-plugin" } +]; +### Plugin not loading +If your plugin doesn’t appear in the init message: +1. **Check the path**: Ensure the path points to the plugin root directory (containing `.claude-plugin/`) +2. **Validate plugin.json**: Ensure your manifest file has valid JSON syntax +3. **Check file permissions**: Ensure the plugin directory is readable +### Skills not appearing +If plugin skills don’t work: +1. **Use the namespace**: Plugin skills require the `plugin-name:skill-name` format when invoked as slash commands +2. **Check init message**: Verify the skill appears in `slash_commands` with the correct namespace +3. **Validate skill files**: Ensure each skill has a `SKILL.md` file in its own subdirectory under `skills/` (for example, `skills/my-skill/SKILL.md`) +### Path resolution issues +If relative paths don’t work: +1. **Check working directory**: Relative paths are resolved from your current working directory +2. **Use absolute paths**: For reliability, consider using absolute paths +3. **Normalize paths**: Use path utilities to construct paths correctly +## See also +- [Plugins](https://code.claude.com/docs/en/plugins) - Complete plugin development guide +- [Plugins reference](https://code.claude.com/docs/en/plugins-reference) - Technical specifications +- [Slash Commands](https://code.claude.com/docs/en/agent-sdk/slash-commands) - Using slash commands in the SDK +- [Subagents](https://code.claude.com/docs/en/agent-sdk/subagents) - Working with specialized agents +- [Skills](https://code.claude.com/docs/en/agent-sdk/skills) - Using Agent Skills diff --git a/raw/_processed/Homarr documentation 1.md b/raw/_processed/Homarr documentation 1.md deleted file mode 100644 index cf740d0..0000000 --- a/raw/_processed/Homarr documentation 1.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: "Homarr documentation" -source: "https://homarr.dev/docs/management/apps/" -author: -published: -created: 2026-04-19 -description: "Apps are the building blocks of your Homarr board." -tags: - - "clippings" ---- -Version: 1.59.2 - -Apps are the building blocks of your Homarr board. Most of the time they are a simple link to a website, but used on your board they also support a simple ping to check if your service is up. Apps are used in the bookmark and app widget. - -## Create an app - -To create an app you can click on the button on the top right of the apps management page: - -![[881d180a726437fe08748cfbe467767d_MD5.png]] - -Next, you'll need to fill out the required fields to configure the app: - -![[9008c71880a52ee44f44d3f211f238cc_MD5.png]] - -### Name - -The name must be at least one character long and can be chosen freely. - -### Icon URL - -This is the URL to the icon that will be displayed on the app widget. It can be a url to an image in the internet, one from the included icon repositories or a local file uploaded through the upload button. - -![[bc56e670b2dfd62977a82e503178a9fe_MD5.png]] - -### Description - -An optional description that can be shown as tooltip on the app widget. - -### URL - -The URL to the website you want to link to. Clicking on the app widget or bookmark will open this URL. - -### Ping URL - -When you want to use another url for the simple status check you can set it here. This will allow you to set a different URL for the ping than the URL that is opened when clicking on the app widget. It's useful when you want to ping the service internally for example with a custom ip but open the website externally. - -## List of apps - -On the apps management page you find all apps that exist in your Homarr instance. You can edit and delete them. - -![[57882a4a4257df5162df73d51af51217_MD5.png]] \ No newline at end of file diff --git a/raw/_processed/Homarr documentation 2.md b/raw/_processed/Homarr documentation 2.md deleted file mode 100644 index d67fb8a..0000000 --- a/raw/_processed/Homarr documentation 2.md +++ /dev/null @@ -1,259 +0,0 @@ ---- -title: "Homarr documentation" -source: "https://homarr.dev/docs/management/boards/" -author: -published: -created: 2026-04-19 -description: "Each dashboard is called a \"board\"." -tags: - - "clippings" ---- -Version: 1.59.2 - -Each dashboard is called a "board". You can create as many boards as you want. Boards can be restricted to user groups. A user may also have a "home board" which they will see at the root path (e.g. my-homarr.com or my-homarr.com/board). Other boards can be viewed by direct links (e.g. my-homarr.com/board/smart-home) or via the management pages. - -Names of boards must be unique because this will be used in the URL to load the desired board. - -## Create a new board - -When creating a board, the availability of the board name will be checked for you. - -![[a24328bb659734869ada42365e4b3412_MD5.png]] - -### Name - -The name must not include any special characters and must be at least one character long. Underscores and hyphen-minus are allowed. - -### Column count - -Homarr has a complex drag and drop system that can be used from the browser. The column count defines how many horizontal columns are available to drag and drop elements to. - -### Public - -This will enable public access for everyone - regardless of whether they are logged in or not. This can be really useful if you want to have public boards in your company or for family and fiends. Modifications for public boards must be allowed explicitly using user groups and their permissions. - -## Board settings - -You navigate to the board settings by clicking on these three dots: - -![[e9b34839736ba9a0df9adc491254154d_MD5.png]] - -Alternatively, you can also navigate from the board page itself using the cog icon at the top right: - -![[a49017599d269ff8220d5ed156f21d1d_MD5.png]] - -### General - -#### Page title - -This is the title that will be visible at the top left in the navigation bar: - -![[4ce942c5eb9157a9a6a0fc6e4d4b46a5_MD5.png]] - -This field is optional and Homarr will fall back to "Homarr" if nothing is set. - -#### Meta title - -This is the secondary title of the page that is not directly visible in the page itself. Browser will use it to set the title of tabs: - -![[baffdc8d59cddf70731dc4da1eff35c5_MD5.png]] - -Homarr will fall back to the board name and a suffix if nothing is set. - -#### Logo image URL - -This is the URL that is used for the image at the top left. Homarr will fall back to the Homarr logo if nothing is set. - -#### Favicon image URL - -This is the URL that is used for the favicon in the tab title. Homarr will fall back to the Homarr logo if nothing is set. - -### Layout - -In this section you can configure the different responsive layouts. Depending on your screens width the layout will change. - -![[d11998dcc429dbd2520c6416bb01da54_MD5.png]] - -On each element the position and size of items can be changed seperately. When adding a new layout the position and sizes will automatically be generated depending on the column count. When adding a new item / dynamic section that will always be 1x1 on each layout and placed on the first available position. - -#### Name - -The name of the layout can be choosen freely. It is only used for the management and will not be visible on the board. - -#### Column count - -Amount of columns for this layout. Defines how many items can be placed in a row. When changed it will automatically adjust the position and size of the items. - -#### Breakpoint - -Minimum width of the screen where the layout will be used. Once the minmum of the next layout is reached the layout will change. - -#### Preview - -![[aa56ffcc83b0c5932fa1dde8bd42489e_MD5.png]] ![[01366fd6e092541dda0b95fada57724e_MD5.png]] ![[bfe66f5007a785b7e127b17602cfb3e7_MD5.png]] - -### Background - -#### Background image URL - -Homarr can display a background image behind apps and widgets. This URL can be used to define what image should be shown. - -#### Background image attachment - -This defines whether the background should move when the user scrolls. - -#### Background image size - -This defines whether the background should cover the entire page (and possibly be cropped) or never be cropped but may not cover the entire page. - -#### Background image repeat - -This defines whether the background should be repeated if it cannot cover the entire page. This option can be useful if you have patterns that can be repeated easily (e.g. patterns): - -![[0aec7557f58509eb96e54dc5517c0e88_MD5.png]] - -### Appearance - -#### Primary color - -Color that can be chosen freely to give accents to active elements. - -#### Secondary color - -Color that can be chosen freely to give accents. - -#### Opacity - -Opacity of the colors. - -#### Icon color - -Change the color of your bookmark / app icons. - -![[c1cd2ff8e5f380baafcea8a4be8171c7_MD5.png]] - -#### Item radius - -Change the radius of your items / categories. - -![[fc51892a524d2d82d1a00a29047de9d4_MD5.png]] - -### Custom CSS - -This is the field where you can enter custom CSS. The styling will only be applied on the respective board page. - -[See this guide on how to work with custom CSS](https://homarr.dev/docs/next/advanced/styling/). - -### Behaviour - -#### Disable app status - -This will disable the status check for apps. - -### Access control - -With the access control, you can permit a single user or a group to your board. The users and groups can have one of these three levels of access: - -| **Permission Level** | View board | Edit mode | Settings | Danger zone (eg. delete) | -| --- | --- | --- | --- | --- | -| View board | X | | | | -| Modify board | X | X | X | | -| Full access | X | X | X | X | - -The permission level can only be changed after adding the user / group: - -![[1aba670865350eb017d5657555c86be6_MD5.png]] - -If the board is private and the user is not added in any of the three tabs, they cannot access the board. They also do not see the board on the start page nor do they have access to any links for the board. - -Groups that have high permissions (e.g. administrator or all board permissions) will be shown as "inherited". They are permitted implicitly due to their permissions. - -After editing permissions, the save button below the table must be pressed. Otherwise, all changes will be discarded. - -### Danger zone - -#### Rename - -Renaming a board will break all existing links to it permanently with no redirect. - -#### Board visibility - -By default, boards will be private. This means only authenticated users that are authorized have access. Making a board public will expose it to everyone - including unauthenticated users. - -#### Delete - -This will permanently delete the board. This action is irreversible and cannot be undone. - -## Delete boards - -The deletion of boards is permanent and cannot be undone. There are two ways to delete a board: - -- Navigate to the settings of your board, open the "Danger zone" dropdown and click on the "delete this board" button. -- Navigate to the list of boards in the management pages, click the three dots and click on "delete permanently". - -Both actions will execute the same deletion process. - -## Duplicate boards - -> [!-secondary] -secondary -> note -> -> Duplicating a board will not copy the users and groups that have access to the board nor the integrations the user does not have access to. - -Duplicating a board will create a new board with the same settings and layout as the original board. You can duplicate a board by clicking on the three dots in the list of boards and selecting "Duplicate board". - -![[5c10ca91f544a97d272fa5f49c96b92d_MD5.png]] - -## Setting boards as your home board - -The home board is the dashboard, that will be shown at the root path of Homarr or if no board name was passed in the URL. All the following paths will lead to the home board: - -- `my-homarr.com` -- `my-homarr.com/boards` - -Your home board will have a special small badge at the top right in the list of boards: - -![[67bba8348b6fd2d99a36ff977c46c5c7_MD5.png]] - -### For yourself - -To set the home board yourself, the easiest option is to set it directly in the list of boards: - -![[4e0f763cda0db2a95ff1d3783d68005d_MD5.png]] - -Alternatively, you can also define it via your user profile: - -1. Click on your user profile at the top right -2. Click on `Your preferences` -3. Change the home board in the `home board` dropdown and click on `Save`. - -### For other users - -1. Navigate to the users: `Management` > `Users` > `Manage` -2. Click on the username of the user that you want to adjust -3. Select the desired home board via the dropdown and click on `Save` - ![[3551fc64e0a03b35328abd3b16a0607b_MD5.png]] - -### For user groups - -1. Navigate to the user groups: `Management` > `Users` > `Groups` > `Manage` -2. Go to tab `Settings` -3. Select the desired home board via the dropdown and click on `Save` - ![[15206a0710f5e9d44953db686d825c0c_MD5.png]] - -### For whole server - -You can also set a global home board that will be used for all users that have not set a home board themselves. It will also be used for anonymous users. - -1. Navigate to the settings: `Management` > `Settings` > `Boards` -2. Select the desired home board via the dropdown and click on `Save` - ![[ec0c2e539f26464aad191e4cecfbdb33_MD5.png]] - -> [!-secondary] -secondary -> note -> -> For the global home board you can only select boards that are public. - -### Mobile home board - -Same as the home board, you can also set a mobile home board. It will be used for devices that are detected as mobile devices. (Using User-Agent header) \ No newline at end of file diff --git a/raw/_processed/Homarr documentation 3.md b/raw/_processed/Homarr documentation 3.md deleted file mode 100644 index 54ad321..0000000 --- a/raw/_processed/Homarr documentation 3.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "Homarr documentation" -source: "https://homarr.dev/docs/management/certificates/" -author: -published: -created: 2026-04-19 -description: "On this page you can manage your trusted certificates." -tags: - - "clippings" ---- -Version: 1.59.2 - -On this page you can manage your trusted certificates. For example if you use a self signed certificate for one of the integrations you want to connect, you can add it here. - -Below you can see a screenshot of the certificates page. The items show the subject, filename and when it expires. The color of the icon indicates how long it is valid. - -![[07b46a68e92bec71673a12d3a1cb25b8_MD5.png]] - -| Color | Meaning | -| --- | --- | -| 🟩 Green | Valid for more than 30 days | -| 🟨 Yellow | Valid for less than 30 days | -| 🟧 Orange | Valid for less than a week | -| 🟥 Red | Valid for less than a day | - -## Opening the certificates page - -Navigate to `Management` > `Tools` > `Certificates`. - -## Add a certificate - -To add a certificate click on the "Add certificate" button. - -![[ed90e733287f790df54455fe27ada45b_MD5.png]] - -Then select the certificate file you want to add. - -![[1daf3fcccddfdfa5fa32e60556e21b4c_MD5.png]] - -And click the "Add" button. - -## Delete a certificate - -To delete a certificate you can click on the trash icon in the certificate card. - -![[4fa61318d5941ae809e751cbe4b0aa8b_MD5.png]] - -Then confirm the deletion. - -## Managing it through file system - -The certificates are stored in the `/appdata/trusted-certificates` directory which is mounted through `/appdata`. This means you can automate the update of the certificates by simply replacing or adding a new file in the directory. - -## Obtaining certificates - -Every integration has its own way of obtaining certificates. Generally it is recommended to search for the documentation of the integration you are using. Most of the time you can find the certificate in the file system of the integration. Below you can find instructions for some of the integrations. - -### Pi-hole (v6) - -Since version 6 of Pi-hole, the web interface can be accessed through HTTPS. The certificate can be found in the path `/etc/pihole/tls_ca.crt`. To add the certificate, this file needs to be copied and uploaded to Homarr. You can find more details regarding SSL / TLS for Pi-hole [here](https://docs.pi-hole.net/api/tls/). \ No newline at end of file diff --git a/raw/_processed/Homarr documentation 4.md b/raw/_processed/Homarr documentation 4.md deleted file mode 100644 index fac88af..0000000 --- a/raw/_processed/Homarr documentation 4.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: "Homarr documentation" -source: "https://homarr.dev/docs/management/integrations/" -author: -published: -created: 2026-04-19 -description: "Integrations are connections to supported third party applications." -tags: - - "clippings" ---- -Version: 1.59.2 - -Integrations are connections to supported third party applications. This page will describe the process of managing integrations but the process may vary depending on your specific integration. Check [the available integrations](https://homarr.dev/docs/category/integrations) for further information. - -## Create an integration - -To create an integration, you can choose the supported application from the dropdown at the top right: - -![[b403f6e2ad41cd95c9ef0ab2c9037757_MD5.png]] - -Next, you'll need to fill out the required fields to configure the integration: - -![[28719542ceeb925d0a749a6fbd41b81a_MD5.png]] - -### Name - -Must be at least 1 character long, can be chosen freely. - -### Url - -This must be the base URL of the application where Homarr should connect to. A few examples for this field include: - -- [http://sabnzbd.example.com](http://sabnzbd.example.com/) -- [https://example.com/sabnzbd](https://example.com/sabnzbd) - -You must not append any path after the base URL. Some examples for incorrect usage: - -- [http://sabnzbd.example.com/settings](http://sabnzbd.example.com/settings) -- [https://example.com/sabnzbd/settings](https://example.com/sabnzbd/settings) - -### Secrets - -An integration may or may not require secrets to function. To process to obtain them is usually [documented in the integration pages](https://homarr.dev/docs/category/integrations). Secrets are encrypted using a symmetric encryption and stored in the database. To improve security, they will never be passed to the client and requests to the integrations are performed from the host where Homarr is running on. - -### Linking applications - -During the creation of an integration you can choose to add / link an application to the integration. If you want to add one, you can simply specify the app url which will be used for opening the application from Homarr. The linked application will also be used for any links the integration widget contains. If you already have an application created, you can also link it to the integration by selecting it from the dropdown. On the edit page you can always change or remove the linked application. - -### Testing and saving integration - -It is not allowed to create an integration without passing the test. This is to ensure that you minimize the amount of broken applications on your Homarr instance. The test and create button will perform a network request to the application and authenticate if required. - -## Managing permissions - -On the edit page of an integration, you can manage which users / groups can - -- **Select the integration in items:** Allows users to select the integration and showing data on their board. -- **Interact with the integration:** Allows users to perform actions on the integration, such as pausing a download. -- **Full control over the integration:** Allows users to modify the integration properties, including the URL and secrets. - -![[2af628de56b4534249e652d8e4334fdd_MD5.png]] - -## Troubleshooting connection - -The connection to your integrations can fail due to many factors. Most of the time it should show you the reason why it failed. If it doesn't, you can follow these steps to troubleshoot the issue: - -1. Check whether you are using the correct URL and secrets. - - The URL must be the base URL of the application, **without any paths**. - - The secrets must be correct and have the correct permissions. -2. If you use https to connect to the application, check the chapter below about [certificate issues](#certificate-issues). -3. Check whether you followed the Homarr documentation and didn't skip any steps. This is the most often mistake that create many noisy support requests and following all steps will often resolve the problems. -4. Check Homarr's logs for more information. As we have no control over breaking changes in upstream APIs and third party software, they can break without notice in unexpected ways which can also lead to errors within Homarr. In such case, these occurrences must be reported and fixed within the source code of Homarr. -5. Check whether the host can reach the destination hostname / IP using `ping` and `curl` or `wget` afterward. Execute this command on the host machine, not inside containers, to check whether it can connect or not. -6. Check whether the container / pod can reach the destination hostname / IP. Execute the same commands in the shell inside the container / pod. -7. Check your reverse proxy / authentication proxy logs for failures / hints -8. Check your security log of tunnels and VPNs -9. Check your router for security events -10. Check your VLAN configuration and firewall rules -11. Check your DNS settings for the host machine and the containers / pods and whether they can resolve the hostnames -12. Check throughput and stability of your network connection using `iperf3` -13. Check syslog / drivers of your OS for hints -14. Check logs of your destination applications (eg. SABnzbd) -15. Attempt to disable CSRF / tamper protections when absolutely no other workaround available -> this comes with some security implications - be careful! Re-enable if this didn't fix the issue. - -If none of these troubleshooting steps worked, you can request support from our team in Discord or GitHub. - -### Certificate issues - -If you are using a self-signed certificate you'll need to add it to the [trusted certificates](https://homarr.dev/docs/management/certificates) in Homarr. Most of the time you should also get a button to add the certificate automatically when you try to connect to the integration. Please check that the certificate is the one you are expecting to prevent Man in the Middle attacks. For some integrations, you can find a guide on how to retrieve the certificate [here](https://homarr.dev/docs/management/certificates/#obtaining-certificates). \ No newline at end of file diff --git a/raw/_processed/Homarr documentation 5.md b/raw/_processed/Homarr documentation 5.md deleted file mode 100644 index 6d64b40..0000000 --- a/raw/_processed/Homarr documentation 5.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "Homarr documentation" -source: "https://homarr.dev/docs/management/settings/" -author: -published: -created: 2026-04-19 -description: "The settings page has a few options that will be applied to the entire Homarr application." -tags: - - "clippings" ---- -Version: 1.59.2 - -The settings page has a few options that will be applied to the entire Homarr application. They may require a full page reload for changes to apply. - -## Analytics - -By default, Homarr is collecting anonymous analytics to identify issues and prioritize bugfixes and improvements. The data is never shared with any third-parties and is fully GDPR & CCPA compliant. The software being used is [Umami Analytics](https://umami.is/) which is fully open source. The main server software can be found [here](https://github.com/umami-software/umami) and [this node library](https://github.com/umami-software/node) to perform server side calls to the API. - -A full list of the collected data by default can be found here: [https://umami.is/docs/metric-definitions](https://umami.is/docs/metric-definitions). - -We understand that you might not want Homarr to communicate with our services. By unchecking the `Send anonymous analytics` checkbox and reloading the full page, all communication by Umami will be disabled and no data will be collected. If you are paranoid, you can permanently block `umami.homarr.dev` from your DNS / firewall. - -Additionally, you opt in to more data collection to help us provide more useful data. - -### Integration data - -Enabling this optional data will send the types of integrations (e.g. SABnzbd, Sonarr,...) and how many you have configured of them. This will not include any URLs, names, secrets, errors and others. This is disabled by default. - -### Widget data - -Enabling this optional data will send the types of widgets (e.g. downloads, media streams, iframe,...) and how many you have configured of them. This will not include any URLs, names, secrets, errors and others. This is disabled by default. - -### Users data - -Enabling this optional data will send the count of users and whether you activated SSO. This will not include any usernames, passwords, emails, URLs, authentication flows or client IDs. This is disabled by default. - -## Search Engine Optimization (SEO) - -Big companies [like Google, Microsoft, Baidu and Yandex](https://de.wikipedia.org/wiki/Web-Index) will use [web crawlers](https://de.wikipedia.org/wiki/Webcrawler) to index the Internet for new websites & pages. This is desirable in many cases (for example when selling products in an online shop) but can lead to unwanted traffic and attention to your personal dashboard. Homarr is requesting the crawlers to not index Homarr instances by default for this reason. If you use Homarr as a public website and want it to be searchable on these search engines, you can disable these settings. Please note that Homarr doesn't have control over what the crawlers do; it is a mere request to them to not perform these actions but will not guarantee that your website doesn't land on some index. - -### No index - -This will ask crawlers to not index your Homarr instance on any indexes. It is up to the crawler to properly respect this request. By default, this setting is enabled. Disabling it will allow indexing. - -### No follow - -If indexing is allowed, crawlers will also attempt to follow any links on your page to further "discover" new parts of the Internet and on your website. By default, this setting is enabled and will ask crawlers to not follow any links. Crawler of different companies may behave differently when indexing is prohibited and following is allowed. - -### No translate - -Google and Chrome on Android will prompt users to translate pages that are not in their device language. This can lead to some shifting and can be undesired in some cases. By enabling this, you ask crawlers to never translate and never prompt users for translation. It should be noted that some browsers will ignore this and translate regardless. - -### No site links search box - -This setting is exclusive to Google. [Google will create a box below your domain](https://developers.google.com/search/docs/appearance/structured-data/sitelinks-searchbox) that lists the paths that were discovered by the "folowing". The user can search them directly in Google. You can ask the crawlers to not allow searches by enabling this setting. This setting is disabled by default. - -## Boards - -### Global home board - -You can set a global home board that will be used for all users that have not set a home board themselves. It will also be used for anonymous users. Note that the board must be public to be used as a global home board. - -### Global mobile board - -You can set a global mobile board. It will be shown instead of the global home board on mobile devices that can be detected by Homarr. (Using the User-Agent header). It will similar to the global home board be as fallback for normal users and for any anonymous users. It also has to be public. - -### App status - -#### Enable status by default - -You can decide if the app status should be enabled by default when adding a new app to the board. - -#### Force disable status - -You can decide if the app status should be disabled for all boards. - -## Appearance - -### Default color scheme - -You can set the default color scheme for all users that have not set a color scheme themselves. - -## Culture - -### Default language - -You can set the default language for all users that have not set a language themselves. \ No newline at end of file diff --git a/raw/_processed/Homarr documentation 6.md b/raw/_processed/Homarr documentation 6.md deleted file mode 100644 index 5e530eb..0000000 --- a/raw/_processed/Homarr documentation 6.md +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: "Homarr documentation" -source: "https://homarr.dev/docs/integrations/docker/" -author: -published: -created: 2026-04-19 -description: "Docker is a platform where you can run your applications in containers, allowing for easy deployment and management of applications." -tags: - - "clippings" ---- -Version: 1.59.2 - -![[9800887d27cbbc03c2506ea136ed49e0_MD5.svg]] - -## Docker - -Containers - -Docker is a platform where you can run your applications in containers, allowing for easy deployment and management of applications. - -### Widgets & Capabilities - -Docker statsStats of your containersThis widget can only be used with administrator privileges - -[Details](https://homarr.dev/docs/widgets/docker-containers) - -## Enabling the Docker integration - -This integration must first be enabled. If you directly run on the host system and you have docker installed, it will be enabled by default. Otherwise, you'll need to mount the [docker socket](https://docs.docker.com/engine/security/protect-access/) to the Homarr container, so Homarr can interact with the Docker service. - -In Docker Compose, you can simply add this line: - -```yaml -#---------------------------------------------------------------------# -# Homarr - A simple, yet powerful dashboard for your server. # -#---------------------------------------------------------------------# -services: - homarr: - container_name: homarr - image: ghcr.io/homarr-labs/homarr:latest - restart: unless-stopped - volumes: - - /var/run/docker.sock:/var/run/docker.sock # <--- add this line here! - - ./homarr/appdata:/appdata - environment: - - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with \`openssl rand -hex 32\` - ports: - - '7575:7575' -``` - -With docker run, add this parameter: `-v /var/run/docker.sock:/var/run/docker.sock`. In Windows, you'll need to adjust the slashes: `-v //var/run/docker.sock:/var/run/docker.sock` - -### Managing your Docker containers within Homarr - -Homarr allows you to interact with Docker containers running on your system. You can **restart**, **stop**, **start**, **refresh** and **remove** containers. A search also allows you to search through your containers. - -Additionally, if you have a lot of containers you can search and filter them by **container** or **image** name: - -![[01d1441e18efd5d0f8d27889d8e974b8_MD5.png]] - -#### Add apps from containers - -Homarr also lets you add apps from containers. You can simply select all containers you want to add an app for and then click the `Add to Homarr` button. This will open a dialog where you can specify the web addresses for all of them: - -![[2edee76f6ec0b063158c7ac29ace072e_MD5.png]] - -Once you've changed the web addresses, click the `Add` button to add the apps to Homarr. They are then available in the app list and can be used as normally added apps. - -![[e3c6e698470486dcc2d1a155f62b9102_MD5.png]] - -### Configuration - -Currently Homarr supports one label for configuration of the containers: - -- **homarr.hide:** If set to any value, the container will be hidden from the Docker Containers widget and tools page. - -### Security - -Mounting docker sockets can be risky, as they permit full control over your docker service. As an example, a thread actor could abuse Homarr use the socket to start, stop or delete containers on your system. - -Therefore we recommend the usage of a socket proxy, which can prohibit certain actions. A few examples include: - -- [https://github.com/linuxserver/docker-socket-proxy](https://github.com/linuxserver/docker-socket-proxy) -- [https://github.com/Tecnativa/docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) - -See documentation of the respective proxies on how to configure them. Homarr may behave in unexpected ways when you use proxies. - -#### Permissions - -Homarr needs the following permissions from the Docker API: - -- Containers/Start -- Containers/Stop -- Containers/Restart -- Containers/Remove - -For socket proxies, you will need these permissions: - -- `CONTAINERS=1` -- `POST=1` - -**Caution:** `POST` access is security critical as it provides extensive capabilities to modify your docker environment. Please leave it disabled if you're concerned about this. - -As a workaround, you can use [LSIO's socket proxy](https://github.com/linuxserver/docker-socket-proxy) and set the following: - -- ALLOW\_START=1 -- ALLOW\_STOP=1 -- ALLOW\_RESTARTS=1 - -These will work even with `POST=0`. - -You lose the ability to remove containers, but start, stop and restarts should work just fine. - -#### Connecting to Docker via Socket Proxies - -To connect to Docker via a socket proxy, you'll need to add these two environment variables in the compose file: - -- `DOCKER_HOSTNAMES=` -- `DOCKER_PORTS=` - -Refer: [https://homarr.dev/docs/advanced/environment-variables/](https://homarr.dev/docs/advanced/environment-variables/) - -You will also need to add Homarr to the network of your socket proxy. You can do it like this: - -1. Add the network to your compose file (with appropriate changes): -```yaml -networks: - socket-proxy: - name: socket-proxy # <--- change this to the name of the network as set up by the socket proxy - external: true -``` -1. Add the network to the homarr service in the compose file: -```yaml -networks: - - socket-proxy -``` -1. Finally, if it is present, remove the default docker socket connection under `volumes` in the homarr service. \ No newline at end of file diff --git a/raw/_processed/Homarr documentation 7.md b/raw/_processed/Homarr documentation 7.md deleted file mode 100644 index 3e89b6e..0000000 --- a/raw/_processed/Homarr documentation 7.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "Homarr documentation" -source: "https://homarr.dev/docs/integrations/github/" -author: -published: -created: 2026-04-19 -description: "GitHub is a web-based platform for version control and collaboration." -tags: - - "clippings" ---- -Version: 1.59.2 ![[220dc26834a2198b9c037048f9297429_MD5.svg]] - -## GitHub - -Version ControlSoftware - -GitHub is a web-based platform for version control and collaboration. - -### Widgets & Capabilities - -ReleasesDisplays a list of the current version of the given repositories with the given version regex. - -[Details](https://homarr.dev/docs/widgets/releases) - -### Adding the integration - -You can find how to add the integration on the [Integrations Management](https://homarr.dev/docs/management/integrations) documentation page. \ No newline at end of file diff --git a/raw/_processed/Homarr documentation 8.md b/raw/_processed/Homarr documentation 8.md deleted file mode 100644 index ba98000..0000000 --- a/raw/_processed/Homarr documentation 8.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: "Homarr documentation" -source: "https://homarr.dev/docs/integrations/nextcloud/" -author: -published: -created: 2026-04-19 -description: "Nextcloud is a self-hosted productivity platform that provides file storage, collaboration tools, and more." -tags: - - "clippings" ---- -Version: 1.59.2 ![[1fd2b1bbbf1e85181aaede0b963c13b2_MD5.svg]] - -## Nextcloud - -CalendarNotifications - -Nextcloud is a self-hosted productivity platform that provides file storage, collaboration tools, and more. - -### Widgets & Capabilities - -CalendarDisplay events from your integrations in a calendar view within a certain relative time period - -[Details](https://homarr.dev/docs/widgets/calendar) - -NotificationsDisplay notification history from an integration - -[Details](https://homarr.dev/docs/widgets/notifications) - -### Adding the integration - -You can find how to add the integration on the [Integrations Management](https://homarr.dev/docs/management/integrations) documentation page. \ No newline at end of file diff --git a/raw/_processed/Homarr documentation 9.md b/raw/_processed/Homarr documentation 9.md deleted file mode 100644 index ab5b11a..0000000 --- a/raw/_processed/Homarr documentation 9.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: "Homarr documentation" -source: "https://homarr.dev/docs/integrations/q-bittorent/" -author: -published: -created: 2026-04-19 -description: "qBittorrent is a free and open-source BitTorrent client." -tags: - - "clippings" ---- -Version: 1.59.2 ![[461ff1f69c2c6a281e0d25b2f6d039de_MD5.svg]] - -## qBittorrent - -Torrent client - -qBittorrent is a free and open-source BitTorrent client. - -### Widgets & Capabilities - -Download ClientAllows you to view and manage your Downloads from both Torrent and Usenet clients. - -[Details](https://homarr.dev/docs/widgets/downloads) - -### Adding the integration - -You can find how to add the integration on the [Integrations Management](https://homarr.dev/docs/management/integrations) documentation page. - -### Secrets - -- Username & Password - -| Name | Description | -| --- | --- | -| Username | Account username for authentication. | -| Password | Account password for authentication. | \ No newline at end of file diff --git a/raw/_processed/Homarr documentation.md b/raw/_processed/Homarr documentation.md index 055b54d..328e905 100644 --- a/raw/_processed/Homarr documentation.md +++ b/raw/_processed/Homarr documentation.md @@ -77,4 +77,399 @@ API key authentication enables programmatic access for: [https://homarr.dev](https://homarr.dev/) -Servers \ No newline at end of file +Servers +source: "https://homarr.dev/docs/integrations/docker/" +description: "Docker is a platform where you can run your applications in containers, allowing for easy deployment and management of applications." +![[9800887d27cbbc03c2506ea136ed49e0_MD5.svg]] +## Docker +Containers +Docker is a platform where you can run your applications in containers, allowing for easy deployment and management of applications. +### Widgets & Capabilities +Docker statsStats of your containersThis widget can only be used with administrator privileges +[Details](https://homarr.dev/docs/widgets/docker-containers) +## Enabling the Docker integration +This integration must first be enabled. If you directly run on the host system and you have docker installed, it will be enabled by default. Otherwise, you'll need to mount the [docker socket](https://docs.docker.com/engine/security/protect-access/) to the Homarr container, so Homarr can interact with the Docker service. +In Docker Compose, you can simply add this line: +```yaml +#---------------------------------------------------------------------# +# Homarr - A simple, yet powerful dashboard for your server. # +#---------------------------------------------------------------------# +services: + homarr: + container_name: homarr + image: ghcr.io/homarr-labs/homarr:latest + restart: unless-stopped + volumes: + - /var/run/docker.sock:/var/run/docker.sock # <--- add this line here! + - ./homarr/appdata:/appdata + environment: + - SECRET_ENCRYPTION_KEY=your_64_character_hex_string # <--- can be generated with \`openssl rand -hex 32\` + ports: + - '7575:7575' +With docker run, add this parameter: `-v /var/run/docker.sock:/var/run/docker.sock`. In Windows, you'll need to adjust the slashes: `-v //var/run/docker.sock:/var/run/docker.sock` +### Managing your Docker containers within Homarr +Homarr allows you to interact with Docker containers running on your system. You can **restart**, **stop**, **start**, **refresh** and **remove** containers. A search also allows you to search through your containers. +Additionally, if you have a lot of containers you can search and filter them by **container** or **image** name: +![[01d1441e18efd5d0f8d27889d8e974b8_MD5.png]] +#### Add apps from containers +Homarr also lets you add apps from containers. You can simply select all containers you want to add an app for and then click the `Add to Homarr` button. This will open a dialog where you can specify the web addresses for all of them: +![[2edee76f6ec0b063158c7ac29ace072e_MD5.png]] +Once you've changed the web addresses, click the `Add` button to add the apps to Homarr. They are then available in the app list and can be used as normally added apps. +![[e3c6e698470486dcc2d1a155f62b9102_MD5.png]] +### Configuration +Currently Homarr supports one label for configuration of the containers: +- **homarr.hide:** If set to any value, the container will be hidden from the Docker Containers widget and tools page. +### Security +Mounting docker sockets can be risky, as they permit full control over your docker service. As an example, a thread actor could abuse Homarr use the socket to start, stop or delete containers on your system. +Therefore we recommend the usage of a socket proxy, which can prohibit certain actions. A few examples include: +- [https://github.com/linuxserver/docker-socket-proxy](https://github.com/linuxserver/docker-socket-proxy) +- [https://github.com/Tecnativa/docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) +See documentation of the respective proxies on how to configure them. Homarr may behave in unexpected ways when you use proxies. +#### Permissions +Homarr needs the following permissions from the Docker API: +- Containers/Start +- Containers/Stop +- Containers/Restart +- Containers/Remove +For socket proxies, you will need these permissions: +- `CONTAINERS=1` +- `POST=1` +**Caution:** `POST` access is security critical as it provides extensive capabilities to modify your docker environment. Please leave it disabled if you're concerned about this. +As a workaround, you can use [LSIO's socket proxy](https://github.com/linuxserver/docker-socket-proxy) and set the following: +- ALLOW\_START=1 +- ALLOW\_STOP=1 +- ALLOW\_RESTARTS=1 +These will work even with `POST=0`. +You lose the ability to remove containers, but start, stop and restarts should work just fine. +#### Connecting to Docker via Socket Proxies +To connect to Docker via a socket proxy, you'll need to add these two environment variables in the compose file: +- `DOCKER_HOSTNAMES=` +- `DOCKER_PORTS=` +Refer: [https://homarr.dev/docs/advanced/environment-variables/](https://homarr.dev/docs/advanced/environment-variables/) +You will also need to add Homarr to the network of your socket proxy. You can do it like this: +1. Add the network to your compose file (with appropriate changes): +```yaml +networks: + socket-proxy: + name: socket-proxy # <--- change this to the name of the network as set up by the socket proxy + external: true +1. Add the network to the homarr service in the compose file: +```yaml +networks: + - socket-proxy +1. Finally, if it is present, remove the default docker socket connection under `volumes` in the homarr service. + +source: "https://homarr.dev/docs/management/boards/" +description: "Each dashboard is called a \"board\"." +Each dashboard is called a "board". You can create as many boards as you want. Boards can be restricted to user groups. A user may also have a "home board" which they will see at the root path (e.g. my-homarr.com or my-homarr.com/board). Other boards can be viewed by direct links (e.g. my-homarr.com/board/smart-home) or via the management pages. +Names of boards must be unique because this will be used in the URL to load the desired board. +## Create a new board +When creating a board, the availability of the board name will be checked for you. +![[a24328bb659734869ada42365e4b3412_MD5.png]] +### Name +The name must not include any special characters and must be at least one character long. Underscores and hyphen-minus are allowed. +### Column count +Homarr has a complex drag and drop system that can be used from the browser. The column count defines how many horizontal columns are available to drag and drop elements to. +### Public +This will enable public access for everyone - regardless of whether they are logged in or not. This can be really useful if you want to have public boards in your company or for family and fiends. Modifications for public boards must be allowed explicitly using user groups and their permissions. +## Board settings +You navigate to the board settings by clicking on these three dots: +![[e9b34839736ba9a0df9adc491254154d_MD5.png]] +Alternatively, you can also navigate from the board page itself using the cog icon at the top right: +![[a49017599d269ff8220d5ed156f21d1d_MD5.png]] +### General +#### Page title +This is the title that will be visible at the top left in the navigation bar: +![[4ce942c5eb9157a9a6a0fc6e4d4b46a5_MD5.png]] +This field is optional and Homarr will fall back to "Homarr" if nothing is set. +#### Meta title +This is the secondary title of the page that is not directly visible in the page itself. Browser will use it to set the title of tabs: +![[baffdc8d59cddf70731dc4da1eff35c5_MD5.png]] +Homarr will fall back to the board name and a suffix if nothing is set. +#### Logo image URL +This is the URL that is used for the image at the top left. Homarr will fall back to the Homarr logo if nothing is set. +#### Favicon image URL +This is the URL that is used for the favicon in the tab title. Homarr will fall back to the Homarr logo if nothing is set. +### Layout +In this section you can configure the different responsive layouts. Depending on your screens width the layout will change. +![[d11998dcc429dbd2520c6416bb01da54_MD5.png]] +On each element the position and size of items can be changed seperately. When adding a new layout the position and sizes will automatically be generated depending on the column count. When adding a new item / dynamic section that will always be 1x1 on each layout and placed on the first available position. +#### Name +The name of the layout can be choosen freely. It is only used for the management and will not be visible on the board. +#### Column count +Amount of columns for this layout. Defines how many items can be placed in a row. When changed it will automatically adjust the position and size of the items. +#### Breakpoint +Minimum width of the screen where the layout will be used. Once the minmum of the next layout is reached the layout will change. +#### Preview +![[aa56ffcc83b0c5932fa1dde8bd42489e_MD5.png]] ![[01366fd6e092541dda0b95fada57724e_MD5.png]] ![[bfe66f5007a785b7e127b17602cfb3e7_MD5.png]] +### Background +#### Background image URL +Homarr can display a background image behind apps and widgets. This URL can be used to define what image should be shown. +#### Background image attachment +This defines whether the background should move when the user scrolls. +#### Background image size +This defines whether the background should cover the entire page (and possibly be cropped) or never be cropped but may not cover the entire page. +#### Background image repeat +This defines whether the background should be repeated if it cannot cover the entire page. This option can be useful if you have patterns that can be repeated easily (e.g. patterns): +![[0aec7557f58509eb96e54dc5517c0e88_MD5.png]] +### Appearance +#### Primary color +Color that can be chosen freely to give accents to active elements. +#### Secondary color +Color that can be chosen freely to give accents. +#### Opacity +Opacity of the colors. +#### Icon color +Change the color of your bookmark / app icons. +![[c1cd2ff8e5f380baafcea8a4be8171c7_MD5.png]] +#### Item radius +Change the radius of your items / categories. +![[fc51892a524d2d82d1a00a29047de9d4_MD5.png]] +### Custom CSS +This is the field where you can enter custom CSS. The styling will only be applied on the respective board page. +[See this guide on how to work with custom CSS](https://homarr.dev/docs/next/advanced/styling/). +### Behaviour +#### Disable app status +This will disable the status check for apps. +### Access control +With the access control, you can permit a single user or a group to your board. The users and groups can have one of these three levels of access: +| **Permission Level** | View board | Edit mode | Settings | Danger zone (eg. delete) | +| --- | --- | --- | --- | --- | +| View board | X | | | | +| Modify board | X | X | X | | +| Full access | X | X | X | X | +The permission level can only be changed after adding the user / group: +![[1aba670865350eb017d5657555c86be6_MD5.png]] +If the board is private and the user is not added in any of the three tabs, they cannot access the board. They also do not see the board on the start page nor do they have access to any links for the board. +Groups that have high permissions (e.g. administrator or all board permissions) will be shown as "inherited". They are permitted implicitly due to their permissions. +After editing permissions, the save button below the table must be pressed. Otherwise, all changes will be discarded. +### Danger zone +#### Rename +Renaming a board will break all existing links to it permanently with no redirect. +#### Board visibility +By default, boards will be private. This means only authenticated users that are authorized have access. Making a board public will expose it to everyone - including unauthenticated users. +#### Delete +This will permanently delete the board. This action is irreversible and cannot be undone. +## Delete boards +The deletion of boards is permanent and cannot be undone. There are two ways to delete a board: +- Navigate to the settings of your board, open the "Danger zone" dropdown and click on the "delete this board" button. +- Navigate to the list of boards in the management pages, click the three dots and click on "delete permanently". +Both actions will execute the same deletion process. +## Duplicate boards +> [!-secondary] -secondary +> note +> Duplicating a board will not copy the users and groups that have access to the board nor the integrations the user does not have access to. +Duplicating a board will create a new board with the same settings and layout as the original board. You can duplicate a board by clicking on the three dots in the list of boards and selecting "Duplicate board". +![[5c10ca91f544a97d272fa5f49c96b92d_MD5.png]] +## Setting boards as your home board +The home board is the dashboard, that will be shown at the root path of Homarr or if no board name was passed in the URL. All the following paths will lead to the home board: +- `my-homarr.com` +- `my-homarr.com/boards` +Your home board will have a special small badge at the top right in the list of boards: +![[67bba8348b6fd2d99a36ff977c46c5c7_MD5.png]] +### For yourself +To set the home board yourself, the easiest option is to set it directly in the list of boards: +![[4e0f763cda0db2a95ff1d3783d68005d_MD5.png]] +Alternatively, you can also define it via your user profile: +1. Click on your user profile at the top right +2. Click on `Your preferences` +3. Change the home board in the `home board` dropdown and click on `Save`. +### For other users +1. Navigate to the users: `Management` > `Users` > `Manage` +2. Click on the username of the user that you want to adjust +3. Select the desired home board via the dropdown and click on `Save` + ![[3551fc64e0a03b35328abd3b16a0607b_MD5.png]] +### For user groups +1. Navigate to the user groups: `Management` > `Users` > `Groups` > `Manage` +2. Go to tab `Settings` +3. Select the desired home board via the dropdown and click on `Save` + ![[15206a0710f5e9d44953db686d825c0c_MD5.png]] +### For whole server +You can also set a global home board that will be used for all users that have not set a home board themselves. It will also be used for anonymous users. +1. Navigate to the settings: `Management` > `Settings` > `Boards` +2. Select the desired home board via the dropdown and click on `Save` + ![[ec0c2e539f26464aad191e4cecfbdb33_MD5.png]] +> [!-secondary] -secondary +> note +> For the global home board you can only select boards that are public. +### Mobile home board +Same as the home board, you can also set a mobile home board. It will be used for devices that are detected as mobile devices. (Using User-Agent header) + +source: "https://homarr.dev/docs/management/certificates/" +description: "On this page you can manage your trusted certificates." +On this page you can manage your trusted certificates. For example if you use a self signed certificate for one of the integrations you want to connect, you can add it here. +Below you can see a screenshot of the certificates page. The items show the subject, filename and when it expires. The color of the icon indicates how long it is valid. +![[07b46a68e92bec71673a12d3a1cb25b8_MD5.png]] +| Color | Meaning | +| --- | --- | +| 🟩 Green | Valid for more than 30 days | +| 🟨 Yellow | Valid for less than 30 days | +| 🟧 Orange | Valid for less than a week | +| 🟥 Red | Valid for less than a day | +## Opening the certificates page +Navigate to `Management` > `Tools` > `Certificates`. +## Add a certificate +To add a certificate click on the "Add certificate" button. +![[ed90e733287f790df54455fe27ada45b_MD5.png]] +Then select the certificate file you want to add. +![[1daf3fcccddfdfa5fa32e60556e21b4c_MD5.png]] +And click the "Add" button. +## Delete a certificate +To delete a certificate you can click on the trash icon in the certificate card. +![[4fa61318d5941ae809e751cbe4b0aa8b_MD5.png]] +Then confirm the deletion. +## Managing it through file system +The certificates are stored in the `/appdata/trusted-certificates` directory which is mounted through `/appdata`. This means you can automate the update of the certificates by simply replacing or adding a new file in the directory. +## Obtaining certificates +Every integration has its own way of obtaining certificates. Generally it is recommended to search for the documentation of the integration you are using. Most of the time you can find the certificate in the file system of the integration. Below you can find instructions for some of the integrations. +### Pi-hole (v6) +Since version 6 of Pi-hole, the web interface can be accessed through HTTPS. The certificate can be found in the path `/etc/pihole/tls_ca.crt`. To add the certificate, this file needs to be copied and uploaded to Homarr. You can find more details regarding SSL / TLS for Pi-hole [here](https://docs.pi-hole.net/api/tls/). + +source: "https://homarr.dev/docs/integrations/github/" +description: "GitHub is a web-based platform for version control and collaboration." +Version: 1.59.2 ![[220dc26834a2198b9c037048f9297429_MD5.svg]] +## GitHub +Version ControlSoftware +GitHub is a web-based platform for version control and collaboration. +ReleasesDisplays a list of the current version of the given repositories with the given version regex. +[Details](https://homarr.dev/docs/widgets/releases) +### Adding the integration +You can find how to add the integration on the [Integrations Management](https://homarr.dev/docs/management/integrations) documentation page. + +source: "https://homarr.dev/docs/integrations/nextcloud/" +description: "Nextcloud is a self-hosted productivity platform that provides file storage, collaboration tools, and more." +Version: 1.59.2 ![[1fd2b1bbbf1e85181aaede0b963c13b2_MD5.svg]] +## Nextcloud +CalendarNotifications +Nextcloud is a self-hosted productivity platform that provides file storage, collaboration tools, and more. +CalendarDisplay events from your integrations in a calendar view within a certain relative time period +[Details](https://homarr.dev/docs/widgets/calendar) +NotificationsDisplay notification history from an integration +[Details](https://homarr.dev/docs/widgets/notifications) + +source: "https://homarr.dev/docs/integrations/q-bittorent/" +description: "qBittorrent is a free and open-source BitTorrent client." +Version: 1.59.2 ![[461ff1f69c2c6a281e0d25b2f6d039de_MD5.svg]] +## qBittorrent +Torrent client +qBittorrent is a free and open-source BitTorrent client. +Download ClientAllows you to view and manage your Downloads from both Torrent and Usenet clients. +[Details](https://homarr.dev/docs/widgets/downloads) +### Secrets +- Username & Password +| Name | Description | +| Username | Account username for authentication. | +| Password | Account password for authentication. | + +source: "https://homarr.dev/docs/management/integrations/" +description: "Integrations are connections to supported third party applications." +Integrations are connections to supported third party applications. This page will describe the process of managing integrations but the process may vary depending on your specific integration. Check [the available integrations](https://homarr.dev/docs/category/integrations) for further information. +## Create an integration +To create an integration, you can choose the supported application from the dropdown at the top right: +![[b403f6e2ad41cd95c9ef0ab2c9037757_MD5.png]] +Next, you'll need to fill out the required fields to configure the integration: +![[28719542ceeb925d0a749a6fbd41b81a_MD5.png]] +Must be at least 1 character long, can be chosen freely. +### Url +This must be the base URL of the application where Homarr should connect to. A few examples for this field include: +- [http://sabnzbd.example.com](http://sabnzbd.example.com/) +- [https://example.com/sabnzbd](https://example.com/sabnzbd) +You must not append any path after the base URL. Some examples for incorrect usage: +- [http://sabnzbd.example.com/settings](http://sabnzbd.example.com/settings) +- [https://example.com/sabnzbd/settings](https://example.com/sabnzbd/settings) +An integration may or may not require secrets to function. To process to obtain them is usually [documented in the integration pages](https://homarr.dev/docs/category/integrations). Secrets are encrypted using a symmetric encryption and stored in the database. To improve security, they will never be passed to the client and requests to the integrations are performed from the host where Homarr is running on. +### Linking applications +During the creation of an integration you can choose to add / link an application to the integration. If you want to add one, you can simply specify the app url which will be used for opening the application from Homarr. The linked application will also be used for any links the integration widget contains. If you already have an application created, you can also link it to the integration by selecting it from the dropdown. On the edit page you can always change or remove the linked application. +### Testing and saving integration +It is not allowed to create an integration without passing the test. This is to ensure that you minimize the amount of broken applications on your Homarr instance. The test and create button will perform a network request to the application and authenticate if required. +## Managing permissions +On the edit page of an integration, you can manage which users / groups can +- **Select the integration in items:** Allows users to select the integration and showing data on their board. +- **Interact with the integration:** Allows users to perform actions on the integration, such as pausing a download. +- **Full control over the integration:** Allows users to modify the integration properties, including the URL and secrets. +![[2af628de56b4534249e652d8e4334fdd_MD5.png]] +## Troubleshooting connection +The connection to your integrations can fail due to many factors. Most of the time it should show you the reason why it failed. If it doesn't, you can follow these steps to troubleshoot the issue: +1. Check whether you are using the correct URL and secrets. + - The URL must be the base URL of the application, **without any paths**. + - The secrets must be correct and have the correct permissions. +2. If you use https to connect to the application, check the chapter below about [certificate issues](#certificate-issues). +3. Check whether you followed the Homarr documentation and didn't skip any steps. This is the most often mistake that create many noisy support requests and following all steps will often resolve the problems. +4. Check Homarr's logs for more information. As we have no control over breaking changes in upstream APIs and third party software, they can break without notice in unexpected ways which can also lead to errors within Homarr. In such case, these occurrences must be reported and fixed within the source code of Homarr. +5. Check whether the host can reach the destination hostname / IP using `ping` and `curl` or `wget` afterward. Execute this command on the host machine, not inside containers, to check whether it can connect or not. +6. Check whether the container / pod can reach the destination hostname / IP. Execute the same commands in the shell inside the container / pod. +7. Check your reverse proxy / authentication proxy logs for failures / hints +8. Check your security log of tunnels and VPNs +9. Check your router for security events +10. Check your VLAN configuration and firewall rules +11. Check your DNS settings for the host machine and the containers / pods and whether they can resolve the hostnames +12. Check throughput and stability of your network connection using `iperf3` +13. Check syslog / drivers of your OS for hints +14. Check logs of your destination applications (eg. SABnzbd) +15. Attempt to disable CSRF / tamper protections when absolutely no other workaround available -> this comes with some security implications - be careful! Re-enable if this didn't fix the issue. +If none of these troubleshooting steps worked, you can request support from our team in Discord or GitHub. +### Certificate issues +If you are using a self-signed certificate you'll need to add it to the [trusted certificates](https://homarr.dev/docs/management/certificates) in Homarr. Most of the time you should also get a button to add the certificate automatically when you try to connect to the integration. Please check that the certificate is the one you are expecting to prevent Man in the Middle attacks. For some integrations, you can find a guide on how to retrieve the certificate [here](https://homarr.dev/docs/management/certificates/#obtaining-certificates). + +source: "https://homarr.dev/docs/management/settings/" +description: "The settings page has a few options that will be applied to the entire Homarr application." +The settings page has a few options that will be applied to the entire Homarr application. They may require a full page reload for changes to apply. +## Analytics +By default, Homarr is collecting anonymous analytics to identify issues and prioritize bugfixes and improvements. The data is never shared with any third-parties and is fully GDPR & CCPA compliant. The software being used is [Umami Analytics](https://umami.is/) which is fully open source. The main server software can be found [here](https://github.com/umami-software/umami) and [this node library](https://github.com/umami-software/node) to perform server side calls to the API. +A full list of the collected data by default can be found here: [https://umami.is/docs/metric-definitions](https://umami.is/docs/metric-definitions). +We understand that you might not want Homarr to communicate with our services. By unchecking the `Send anonymous analytics` checkbox and reloading the full page, all communication by Umami will be disabled and no data will be collected. If you are paranoid, you can permanently block `umami.homarr.dev` from your DNS / firewall. +Additionally, you opt in to more data collection to help us provide more useful data. +### Integration data +Enabling this optional data will send the types of integrations (e.g. SABnzbd, Sonarr,...) and how many you have configured of them. This will not include any URLs, names, secrets, errors and others. This is disabled by default. +### Widget data +Enabling this optional data will send the types of widgets (e.g. downloads, media streams, iframe,...) and how many you have configured of them. This will not include any URLs, names, secrets, errors and others. This is disabled by default. +### Users data +Enabling this optional data will send the count of users and whether you activated SSO. This will not include any usernames, passwords, emails, URLs, authentication flows or client IDs. This is disabled by default. +## Search Engine Optimization (SEO) +Big companies [like Google, Microsoft, Baidu and Yandex](https://de.wikipedia.org/wiki/Web-Index) will use [web crawlers](https://de.wikipedia.org/wiki/Webcrawler) to index the Internet for new websites & pages. This is desirable in many cases (for example when selling products in an online shop) but can lead to unwanted traffic and attention to your personal dashboard. Homarr is requesting the crawlers to not index Homarr instances by default for this reason. If you use Homarr as a public website and want it to be searchable on these search engines, you can disable these settings. Please note that Homarr doesn't have control over what the crawlers do; it is a mere request to them to not perform these actions but will not guarantee that your website doesn't land on some index. +### No index +This will ask crawlers to not index your Homarr instance on any indexes. It is up to the crawler to properly respect this request. By default, this setting is enabled. Disabling it will allow indexing. +### No follow +If indexing is allowed, crawlers will also attempt to follow any links on your page to further "discover" new parts of the Internet and on your website. By default, this setting is enabled and will ask crawlers to not follow any links. Crawler of different companies may behave differently when indexing is prohibited and following is allowed. +### No translate +Google and Chrome on Android will prompt users to translate pages that are not in their device language. This can lead to some shifting and can be undesired in some cases. By enabling this, you ask crawlers to never translate and never prompt users for translation. It should be noted that some browsers will ignore this and translate regardless. +### No site links search box +This setting is exclusive to Google. [Google will create a box below your domain](https://developers.google.com/search/docs/appearance/structured-data/sitelinks-searchbox) that lists the paths that were discovered by the "folowing". The user can search them directly in Google. You can ask the crawlers to not allow searches by enabling this setting. This setting is disabled by default. +## Boards +### Global home board +You can set a global home board that will be used for all users that have not set a home board themselves. It will also be used for anonymous users. Note that the board must be public to be used as a global home board. +### Global mobile board +You can set a global mobile board. It will be shown instead of the global home board on mobile devices that can be detected by Homarr. (Using the User-Agent header). It will similar to the global home board be as fallback for normal users and for any anonymous users. It also has to be public. +### App status +#### Enable status by default +You can decide if the app status should be enabled by default when adding a new app to the board. +#### Force disable status +You can decide if the app status should be disabled for all boards. +## Appearance +### Default color scheme +You can set the default color scheme for all users that have not set a color scheme themselves. +## Culture +### Default language +You can set the default language for all users that have not set a language themselves. + +source: "https://homarr.dev/docs/management/apps/" +description: "Apps are the building blocks of your Homarr board." +Apps are the building blocks of your Homarr board. Most of the time they are a simple link to a website, but used on your board they also support a simple ping to check if your service is up. Apps are used in the bookmark and app widget. +## Create an app +To create an app you can click on the button on the top right of the apps management page: +![[881d180a726437fe08748cfbe467767d_MD5.png]] +Next, you'll need to fill out the required fields to configure the app: +![[9008c71880a52ee44f44d3f211f238cc_MD5.png]] +The name must be at least one character long and can be chosen freely. +### Icon URL +This is the URL to the icon that will be displayed on the app widget. It can be a url to an image in the internet, one from the included icon repositories or a local file uploaded through the upload button. +![[bc56e670b2dfd62977a82e503178a9fe_MD5.png]] +### Description +An optional description that can be shown as tooltip on the app widget. +### URL +The URL to the website you want to link to. Clicking on the app widget or bookmark will open this URL. +### Ping URL +When you want to use another url for the simple status check you can set it here. This will allow you to set a different URL for the ping than the URL that is opened when clicking on the app widget. It's useful when you want to ping the service internally for example with a custom ip but open the website externally. +## List of apps +On the apps management page you find all apps that exist in your Homarr instance. You can edit and delete them. +![[57882a4a4257df5162df73d51af51217_MD5.png]] diff --git a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 1.md b/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 1.md deleted file mode 100644 index 95bbccb..0000000 --- a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 1.md +++ /dev/null @@ -1,451 +0,0 @@ ---- -title: "Kling AI: Next-Gen AI Video & AI Image Generator" -source: "https://kling.ai/document-api/apiReference/model/textToVideo" -author: -published: -created: 2026-04-24 -description: -tags: - - "clippings" ---- -## Create Task - -POST `/v1/videos/text2video` - -```bash -curl --request POST \ - --url https://api-singapore.klingai.com/v1/videos/text2video \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "model_name": "kling-v2-6", - "prompt": "A cute little rabbit wearing glasses, sitting at a table, reading a newspaper, with a cup of cappuccino on the table", - "negative_prompt": "", - "duration": "5", - "mode": "pro", - "sound": "on", - "aspect_ratio": "1:1", - "callback_url": "", - "external_task_id": "" - }' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in "Error Code" - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system - "data": { - "task_id": "string", // Task ID, generated by the system - "task_info": { // Task creation parameters - "external_task_id": "string" // Customer-defined task ID - }, - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit ms - "updated_at": 1722769557708 // Task update time, Unix timestamp, unit ms - } -} -``` - -💡 - -Please note that in order to maintain naming consistency, the original model field has been changed to model\_name, so in the future, please use this field to specify the version of the model that needs to be called. -At the same time, we keep the behavior forward-compatible. If you continue to use the original model field, it will not have any impact on the interface call, there will not be any exception, which is equivalent to the default behavior when model\_name is empty (i.e., call the V1 model). - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authorization - -### Request Body - -Model Name - -Enum values：kling-v1kling-v1-6kling-v2-masterkling-v2-1-masterkling-v2-5-turbokling-v2-6kling-v3 - -Whether to generate multi-shot video - -When true: the prompt parameter is invalid, and the first/end frame generation is not supported. - -When false: the shot\_type and multi\_prompt parameters are invalid - -shot\_typestringOptional - -Storyboard method - -Enum values：customizeintelligence - -When multi\_shot is true, this parameter is required - -promptstringOptional - -Positive text prompt - -💡 - -The Omni model can achieve various capabilities through Prompt with elements, images, videos, and other content: - -- Specify elements/images/videos using <<<>>> format, e.g.: <<>>, <<>>, <<>> -- For detailed capabilities, see: [KLING Omni Model User Guide](https://kling.ai/quickstart/klingai-video-o1-user-guide), [Kling VIDEO 3.0 Omni Model User Guide](https://kling.ai/quickstart/klingai-video-3-omni-model-user-guide) - -- Cannot exceed 2500 characters - -- Use <<>> to specify voice, same sequence as voice\_list. Up to 2 voices; when specifying voice, sound must be on. Simpler grammar is better. For example: The man <<>> said, "Hello.". -- When voice\_list is not empty and prompt references voice ID, task is billed as "with voice generation". - -- When multi\_shot is false or shot\_type is intelligence, this parameter must not be empty. - -The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) - -multi\_promptarrayOptional - -Each storyboard cue can include both positive and negative descriptions - -Define the shot sequence number, corresponding prompt word, and duration through the index, prompt, and duration parameters, where: - -- Supports up to 6 storyboards, with a minimum of 1 storyboard. -- The maximum length of the prompt for each storyboard 512 characters. -- The duration of each storyboard should not exceed the total duration, but should not be less than 1. -- The sum of the durations of all storyboards equals the total duration of the current task. - -Load with key:value format as follows: - -```json -"multi_prompt":[ -{"index":int,"prompt":"string","duration":"5"}, -{"index":int,"prompt":"string","duration":"5"} -] -``` - -When multi\_shot is true and shot\_type is customize, this parameter is required. - -Is sound generated simultaneously when generating videos - -Enum values：onoff - -The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) - -The degree of freedom for generating video; the larger the value, the smaller the degree of freedom of the model - -- Value range: \[0, 1\] - -kling-v2.x models do not support this parameter - -Video generation mode - -Enum values：stdpro4k - -- `std`: Standard Mode, basic mode, cost-effective. The output video resolution is 720P. -- `pro`: Professional Mode, generates videos use longer duration but higher quality video output. The output video resolution is 1080P. -- `4k`: 4K Mode, generates videos use longer duration but higher quality video output. The output video resolution is 4K. - -The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) - -camera\_controlobjectOptional - -Terms of controlling camera movement (if not specified, the model will intelligently match based on the input text/images) - -The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) - -▾Hide child attributes - -typestringOptional - -Predefined camera movements type - -Enum values：simpledown\_backforward\_upright\_turn\_forwardleft\_turn\_forward - -- simple: Simple camera movement, you can choose one of six options in "config" - -- down\_back: Camera descends and moves backward ➡️ Pan down and zoom out. The config parameter must be set to "None" under this type. - -- forward\_up: Camera moves forward and tilts up ➡️ Zoom in and pan up. The config parameter must be set to "None" under this type. - -- right\_turn\_forward: Rotate right then move forward ➡️ Rotate right and advance. The config parameter must be set to "None" under this type. - -- left\_turn\_forward: Rotate left then move forward ➡️ Rotate left and advance. The config parameter must be set to "None" under this type. - -configobjectOptional - -Contains 6 fields, used to specify the camera's movement or change in different directions - -- Required when type is simple, not required for other types - -- Choose 1 of the following 6 parameters, only one can be non-zero, others must be 0 - -▾Hide child attributes - -horizontalfloatOptional - -Horizontal, controls the camera's movement along the horizontal axis (translation along the x-axis) - -- Value range: \[-10, 10\] - -- Negative value indicates a translation to the left, positive value indicates a translation to the right - -verticalfloatOptional - -Vertical, controls the camera's movement along the vertical axis (translation along the y-axis) - -- Value range: \[-10, 10\] - -- Negative value indicates a downward translation, positive value indicates an upward translation - -panfloatOptional - -Pan, controls the camera's rotation in the horizontal plane (rotation around the y-axis) - -- Value range: \[-10, 10\] - -- Negative value indicates rotation to the left around y-axis, positive value indicates rotation to the right around y-axis - -tiltfloatOptional - -Tilt, controls the camera's rotation in the vertical plane (rotation around the x-axis) - -- Value range: \[-10, 10\] - -- Negative value indicates rotation down around x-axis, positive value indicates rotation up around x-axis - -rollfloatOptional - -Roll, controls the camera's roll (rotation around the z-axis) - -- Value range: \[-10, 10\] - -- Negative value indicates counterclockwise rotation around z-axis, positive value indicates clockwise rotation around z-axis - -zoomfloatOptional - -Zoom, controls the camera's focal length change, affecting the distance of the field of view - -- Value range: \[-10, 10\] - -- Negative value indicates longer focal length, smaller field of view; positive value indicates shorter focal length, larger field of view - -The aspect ratio of the generated video frame (width:height) - -Enum values：16:99:161:1 - -Video Length, unit: s (seconds) - -Enum values：3456789101112131415 - -The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) - -watermark\_infoobjectOptional - -Whether to generate watermarked results simultaneously - -- Defined by the enabled parameter, format: - -```json -"watermark_info": { "enabled": boolean } -``` - -- true: generate watermarked result, false: do not generate - -- Custom watermarks are not currently supported - -callback\_urlstringOptional - -Callback notification URL for this task result. If configured, the server will actively notify when the task status changes - -- For specific message schema, see [Callback Protocol](https://kling.ai/document-api/apiReference/callbackProtocol) - -external\_task\_idstringOptional - -Customized Task ID - -- Users can provide a customized task ID, which will not overwrite the system-generated task ID but can be used for task queries - -- Must be unique within a single user account - -## More Scene Invocation Examples - -### Text To Video with Multiple Shot - -```bash -curl --location 'https://xxx/v1/videos/text2video' \ ---header 'Authorization: Bearer xxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "model_name": "kling-v3", - "prompt": "", - "multi_prompt": [ - { - "index": 1, - "prompt": "Two friends talking under a streetlight at night. Warm glow, casual poses, no dialogue.", - "duration": "2" - }, - { - "index": 2, - "prompt": "A runner sprinting through a forest, leaves flying. Low-angle shot, focus on movement.", - "duration": "3" - }, - { - "index": 3, - "prompt": "A woman hugging a cat, smiling. Soft sunlight, cozy home setting, emphasize warmth.", - "duration": "3" - }, - { - "index": 4, - "prompt": "A door creaking open, shadowy hallway. Dark tones, minimal details, eerie mood.", - "duration": "3" - }, - { - "index": 5, - "prompt": "A man slipping on a banana peel, shocked expression. Exaggerated pose, bright colors.", - "duration": "3" - }, - { - "index": 6, - "prompt": "A sunset over mountains, small figure walking away. Wide angle, peaceful atmosphere.", - "duration": "1" - } - ], - "multi_shot": true, - "shot_type": "customize", - "duration": "15", - "mode": "pro", - "sound": "on", - "aspect_ratio": "9:16", - "callback_url": "", - "external_task_id": "" -}' -``` - ---- - -## Query Task (Single) - -GET `/v1/videos/text2video/{id}` - -```bash -curl --request GET \ - --url https://api-singapore.klingai.com/v1/videos/text2video/{task_id} \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in "Error Code" - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems - "data": { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) - "task_info": { // Task creation parameters - "external_task_id": "string" // Customer-defined task ID - }, - "task_result": { - "videos": [ - { - "id": "string", // Generated video ID; globally unique - "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) - "watermark_url": "string", // Watermarked video download URL, anti-leech format - "duration": "string" // Total video duration, unit: s (seconds) - } - ] - }, - "watermark_info": { - "enabled": boolean - }, - "final_unit_deduction": "string", // The deduction units of task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Path Parameters - -task\_idstringOptional - -Task ID for text-to-video. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying. - -external\_task\_idstringOptional - -Customized Task ID for text-to-video. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying. - ---- - -## Query Task (List) - -GET `/v1/videos/text2video` - -```bash -curl --request GET \ - --url 'https://api-singapore.klingai.com/v1/videos/text2video?pageNum=1&pageSize=30' \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in Error codes - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, to track requests and troubleshoot problems - "data": [ - { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) - "task_info": { // Task creation parameters - "external_task_id": "string" // Customer-defined task ID - }, - "task_result": { - "videos": [ - { - "id": "string", // Generated video ID; globally unique - "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) - "watermark_url": "string", // Watermarked video download URL, anti-leech format - "duration": "string" // Total video duration, unit: s (seconds) - } - ] - }, - "watermark_info": { - "enabled": boolean - }, - "final_unit_deduction": "string", // The deduction units of task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms - } - ] -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Query Parameters - -Page number - -- Value range: \[1, 1000\] - -Number of items per page - -- Value range: \[1, 500\] \ No newline at end of file diff --git a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 2.md b/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 2.md deleted file mode 100644 index d7e501f..0000000 --- a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 2.md +++ /dev/null @@ -1,705 +0,0 @@ ---- -title: "Kling AI: Next-Gen AI Video & AI Image Generator" -source: "https://kling.ai/document-api/apiReference/model/imageToVideo" -author: -published: -created: 2026-04-24 -description: -tags: - - "clippings" ---- -## Create Task - -POST `/v1/videos/image2video` - -```bash -curl --location --request POST 'https://api-singapore.klingai.com/v1/videos/image2video' \ ---header 'Authorization: Bearer ' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "model_name": "kling-v2-6", - "image": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-2.png", - "image_tail": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png", - "prompt": "Camera zooms out, the girl smiles", - "negative_prompt": "", - "duration": "5", - "mode": "pro", - "sound": "off", - "callback_url": "", - "external_task_id": "" -}' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in "Error Code" - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system - "data": { - "task_id": "string", // Task ID, generated by the system - "task_info": { // Task creation parameters - "external_task_id": "string" // Customer-defined task ID - }, - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit ms - "updated_at": 1722769557708 // Task update time, Unix timestamp, unit ms - } -} -``` - -💡 - -Please note that in order to maintain naming consistency, the original model field has been changed to model\_name. Please use this field to specify the model version in the future. -We maintain backward compatibility. If you continue using the original model field, it will not affect API calls and will be equivalent to the default behavior when model\_name is empty (i.e., calling the V1 model). - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Request Body - -Model Name - -Enum values：kling-v1kling-v1-5kling-v1-6kling-v2-masterkling-v2-1kling-v2-1-masterkling-v2-5-turbokling-v2-6kling-v3 - -imagestringOptional - -Reference Image - -- Supports image Base64 encoding or image URL (ensure accessibility) - -- Important: When using Base64, do NOT add any prefix like `data:image/png;base64,`. Submit only the raw Base64 string. - -- Correct Base64 format: - -``` -iVBORw0KGgoAAAANSUhEUgAAAAUA... -``` - -- Incorrect Base64 format (with data: prefix): - -``` -data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA... -``` - -- Supported image formats: `.jpg / .jpeg / .png` - -- File size: ≤10MB, dimensions: min 300px, aspect ratio: 1:2.5 ~ 2.5:1 - -- At least one of `image` or `image_tail` must be provided; both cannot be empty - -Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. - -image\_tailstringOptional - -Reference Image - End frame control - -- Supports image Base64 encoding or image URL (ensure accessibility) - -- Important: When using Base64, do NOT add any prefix like `data:image/png;base64,`. Submit only the raw Base64 string. - -- Supported image formats: `.jpg / .jpeg / .png` - -- File size: ≤10MB, dimensions: min 300px - -- At least one of `image` or `image_tail` must be provided; both cannot be empty - -- `image_tail`, `dynamic_masks/static_mask`, and `camera_control` are mutually exclusive - only one can be used at a time - -Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. - -Whether to generate multi-shot video - -When true: the prompt parameter is invalid, and the first/end frame generation is not supported. - -When false: the shot\_type and multi\_prompt parameters are invalid - -shot\_typestringOptional - -Storyboard method - -Enum values：customizeintelligence - -When multi\_shot is true, this parameter is required - -promptstringOptional - -Positive text prompt - -💡 - -The Omni model can achieve various capabilities through Prompt with elements, images, videos, and other content: - -- Specify elements/images/videos using <<<>>> format, e.g.: <<>>, <<>>, <<>> -- For detailed capabilities, see: [KLING Omni Model User Guide](https://kling.ai/quickstart/klingai-video-o1-user-guide), [Kling VIDEO 3.0 Omni Model User Guide](https://kling.ai/quickstart/klingai-video-3-omni-model-user-guide) - -- Cannot exceed 2500 characters - -- When multi\_shot is false or shot\_type is intelligence, this parameter must not be empty. - -- Use `<<>>` to specify voice, with the sequence matching the voice\_list parameter order - -- A video generation task can reference up to 2 voices; when specifying a voice, the sound parameter must be "on" - -- The simpler the syntax structure, the better. Example: `The man<<>> said: "Hello"` - -- When voice\_list is not empty and prompt references voice ID, the task will be billed as "with specified voice" - -Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. - -multi\_promptarrayOptional - -Information about each storyboard, such as prompts and duration - -Define the shot sequence number, corresponding prompt word, and duration through the index, prompt, and duration parameters, where: - -- Supports up to 6 storyboards, with a minimum of 1 storyboard. -- The maximum length of the prompt for each storyboard 512 characters. -- The duration of each storyboard should not exceed the total duration, but should not be less than 1. -- The sum of the durations of all storyboards equals the total duration of the current task. - -Load with key:value format as follows: - -```json -"multi_prompt":[ -{"index":int,"prompt":"string","duration":"5"}, -{"index":int,"prompt":"string","duration":"5"} -] -``` - -When multi\_shot is true and shot\_type is customize, this parameter is required. - -element\_listarrayOptional - -Reference Element List, based on element ID from element library - -- Supports up to 3 reference elements - -The elements are categorized into video customization element (named as Video Character Elements) and image customization elements (named as Multi-Image Elements), each with distinct scopes of application. Please exercise caution in distinguishing between them. See [Kling Element Library User Guide](https://kling.ai/quickstart/klingai-element-library-3-user-guide). - -- Load with key:value format as follows: - -```json -"element_list":[ - { "element_id": long }, - { "element_id": long } -] -``` - -Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. - -▾Hide child attributes - -element\_idlongRequired - -Element ID from element library - -voice\_listarrayOptional - -List of voices referenced when generating videos - -- A video generation task can reference up to 2 voices - -- When voice\_list is not empty and prompt references voice ID, the task will be billed as "with specified voice" - -- voice\_id is returned through the voice customization API, or use system preset voices. See [Custom Voices API](https://kling.ai/document-api/apiReference/model/customVoices); NOT the voice\_id of Lip-Sync API - -- element\_list and voice\_list are mutually exclusive and cannot coexist - -Example: - -```json -"voice_list":[ - {"voice_id":"voice_id_1"}, - {"voice_id":"voice_id_2"} -] -``` - -The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) - -Whether to generate sound when generating video - -Enum values：onoff - -The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) - -Flexibility in video generation; higher value means lower model flexibility and stronger relevance to user prompt - -- Value range: \[0, 1\] - -kling-v2.x models do not support this parameter - -Video generation mode - -Enum values：stdpro4k - -- `std`: Standard Mode, basic mode, cost-effective. The output video resolution is 720P. -- `pro`: Professional Mode, generates videos use longer duration but higher quality video output. The output video resolution is 1080P. -- `4k`: 4K Mode, generates videos use longer duration but higher quality video output. The output video resolution is 4K. - -Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. - -static\_maskstringOptional - -Static brush mask area (mask image created by user using motion brush) - -The "Motion Brush" feature includes Dynamic Brush (dynamic\_masks) and Static Brush (static\_mask) - -- Supports image Base64 encoding or image URL (same format requirements as image field) - -- Supported image formats: `.jpg / .jpeg / .png` - -- Aspect ratio must match the input image (image field), otherwise task will fail - -- Resolution of static\_mask and dynamic\_masks.mask must be identical, otherwise task will fail - -Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. - -dynamic\_masksarrayOptional - -Dynamic brush configuration list - -- Can configure multiple groups (up to 6), each containing "mask area" and "motion trajectory" sequence - -Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. - -▾Hide child attributes - -maskstringRequired - -Dynamic brush mask area (mask image created by user using motion brush) - -- Supports image Base64 encoding or image URL (same format requirements as image field) - -- Supported image formats:.jpg /.jpeg /.png - -- Aspect ratio must match the input image (image field), otherwise task will fail - -- Resolution of static\_mask and dynamic\_masks.mask must be identical, otherwise task will fail - -trajectoriesarrayRequired - -Motion trajectory coordinate sequence - -- For 5s video, trajectory length ≤77, coordinate count range: \[2, 77\] - -- Coordinate system uses bottom-left corner of image as origin - -Note 1: More coordinate points = more accurate trajectory. 2 points = straight line between them - -Note 2: Trajectory direction follows input order. First coordinate is start point, subsequent coordinates are connected sequentially - -▾Hide child attributes - -xintRequired - -X coordinate of trajectory point (pixel coordinate with image bottom-left as origin) - -yintRequired - -Y coordinate of trajectory point (pixel coordinate with image bottom-left as origin) - -camera\_controlobjectOptional - -Camera movement control protocol (if not specified, model will intelligently match based on input text/images) - -Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. - -▾Hide child attributes - -typestringRequired - -Predefined camera movement type - -Enum values：simpledown\_backforward\_upright\_turn\_forwardleft\_turn\_forward - -- simple: Simple camera movement, can choose one of six options in "config" - -- down\_back: Camera descends and moves backward ➡️ Pan down and zoom out. config parameter not required - -- forward\_up: Camera moves forward and tilts up ➡️ Zoom in and pan up. config parameter not required - -- right\_turn\_forward: Rotate right then move forward ➡️ Right rotation advance. config parameter not required - -- left\_turn\_forward: Rotate left then move forward ➡️ Left rotation advance. config parameter not required - -configobjectOptional - -Contains 6 fields to specify camera movement in different directions - -- Required when type is "simple"; leave empty for other types - -- Choose only one parameter to be non-zero; rest must be 0 - -▾Hide child attributes - -horizontalfloatOptional - -Horizontal movement - camera translation along x-axis - -- Value range: \[-10, 10\]. Negative = left, Positive = right - -verticalfloatOptional - -Vertical movement - camera translation along y-axis - -- Value range: \[-10, 10\]. Negative = down, Positive = up - -panfloatOptional - -Horizontal pan - camera rotation around y-axis - -- Value range: \[-10, 10\]. Negative = rotate left, Positive = rotate right - -tiltfloatOptional - -Vertical tilt - camera rotation around x-axis - -- Value range: \[-10, 10\]. Negative = tilt down, Positive = tilt up - -rollfloatOptional - -Roll - camera rotation around z-axis - -- Value range: \[-10, 10\]. Negative = counterclockwise, Positive = clockwise - -zoomfloatOptional - -Zoom - controls camera focal length change, affects field of view - -- Value range: \[-10, 10\]. Negative = longer focal length (narrower FOV), Positive = shorter focal length (wider FOV) - -Video duration in seconds - -Enum values：3456789101112131415 - -Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. - -watermark\_infoobjectOptional - -Whether to generate watermarked results simultaneously - -- Defined by the enabled parameter, format: - -```json -"watermark_info": { "enabled": boolean } -``` - -- true: generate watermarked result, false: do not generate - -- Custom watermarks are not currently supported - -callback\_urlstringOptional - -Callback notification URL for task result. If configured, server will notify when task status changes. - -- For specific message schema, see [Callback Protocol](https://kling.ai/document-api/apiReference/callbackProtocol) - -external\_task\_idstringOptional - -Customized Task ID - -- Will not overwrite system-generated task ID, but supports querying task by this ID - -- Must be unique within a single user account - -## Scenario invocation examples - -### Image to video with multi-shot - -```bash -curl --location 'https://xxx/v1/videos/image2video' \ ---header 'Authorization: Bearer xxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "model_name": "kling-v3", - "image": "xxx", - "prompt": "", - "multi_shot": "true", - "shot_type": "customize", - "multi_prompt": [ - { - "index": 1, - "prompt": "Two friends talking under a streetlight at night. Warm glow, casual poses, no dialogue.", - "duration": "2" - }, - { - "index": 2, - "prompt": "A runner sprinting through a forest, leaves flying. Low-angle shot, focus on movement.", - "duration": "3" - }, - { - "index": 3, - "prompt": "A woman hugging a cat, smiling. Soft sunlight, cozy home setting, emphasize warmth.", - "duration": "3" - }, - { - "index": 4, - "prompt": "A door creaking open, shadowy hallway. Dark tones, minimal details, eerie mood.", - "duration": "3" - }, - { - "index": 5, - "prompt": "A man slipping on a banana peel, shocked expression. Exaggerated pose, bright colors.", - "duration": "3" - }, - { - "index": 6, - "prompt": "A sunset over mountains, small figure walking away. Wide angle, peaceful atmosphere.", - "duration": "1" - } - ], - "negative_prompt": "", - "duration": "15", - "mode": "pro", - "sound": "on", - "callback_url": "", - "external_task_id": "" -}' -``` - -### Image to video with element - -```bash -curl --location 'https://api-singapore.klingai.com/v1/images/generations' \ ---header 'Authorization: Bearer xxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "model_name": "kling-v3", - "prompt": "Merge all the characters from the images into the <<>> diagram", - "element_list": [ - { - "element_id": "160" - }, - { - "element_id": "161" - }, - { - "element_id": "159" - } - ], - "image": "xxx", - "resolution": "2k", - "n": "9", - "aspect_ratio": "3:2", - "external_task_id": "", - "callback_url": "" -}' -``` - -```bash -curl --location 'https://xxx/v1/videos/text2video' \ ---header 'Authorization: Bearer xxx' \ ---header 'Content-Type: application/json' \ ---data '{ - "model_name": "kling-v3", - "prompt": "", - "multi_prompt": [ - { - "index": 1, - "prompt": "Two friends talking under a streetlight at night. Warm glow, casual poses, no dialogue.", - "duration": "2" - }, - { - "index": 2, - "prompt": "A runner sprinting through a forest, leaves flying. Low-angle shot, focus on movement.", - "duration": "3" - }, - { - "index": 3, - "prompt": "A woman hugging a cat, smiling. Soft sunlight, cozy home setting, emphasize warmth.", - "duration": "3" - }, - { - "index": 4, - "prompt": "A door creaking open, shadowy hallway. Dark tones, minimal details, eerie mood.", - "duration": "3" - }, - { - "index": 5, - "prompt": "A man slipping on a banana peel, shocked expression. Exaggerated pose, bright colors.", - "duration": "3" - }, - { - "index": 6, - "prompt": "A sunset over mountains, small figure walking away. Wide angle, peaceful atmosphere.", - "duration": "1" - } - ], - "multi_shot": true, - "shot_type": "customize", - "duration": "15", - "mode": "pro", - "sound": "on", - "aspect_ratio": "9:16", - "callback_url": "", - "external_task_id": "" -}' -``` - -### Generate video with voice control - -```bash -curl --location 'https://api-singapore.klingai.com/v1/videos/image2video/' \ ---header 'Authorization: Bearer {Replace your token}' \ ---header 'Content-Type: application/json; charset=utf-8' \ ---data '{ - "model_name": "kling-v2-6", - "image": "Replace the URL of image", - "prompt": "<<>>Ask the people in the picture to say the following words, '\''Welcome everyone'\''", //If a specific dialogue needs to be enclosed in quotation marks - "voice_list": [ - { - "voice_id": "Replace the ID of voice" - } - ], - "duration": "5", - "mode": "pro", - "sound": "on", - "callback_url": "", - "external_task_id": "" -}' -``` - ---- - -## Query Task (Single) - -GET `/v1/videos/image2video/{id}` - -```bash -curl --request GET \ - --url https://api-singapore.klingai.com/v1/videos/image2video/{task_id} \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in "Error Code" - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems - "data": { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) - "watermark_info": { - "enabled": boolean - }, - "task_result": { - "videos": [ - { - "id": "string", // Generated video ID; globally unique - "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) - "watermark_url": "string", // Watermarked video download URL, anti-leech format - "duration": "string" // Total video duration, unit: s - } - ] - }, - "task_info": { // Task creation parameters - "external_task_id": "string" // Customer-defined task ID - }, - "final_unit_deduction": "string", // The deduction units of task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Path Parameters - -task\_idstringOptional - -Task ID for image to video - -- Request path parameter, fill value directly in request path - -- Choose one between task\_id and external\_task\_id for querying - -external\_task\_idstringOptional - -Customized Task ID for image to video - -- The external\_task\_id provided when creating the task - -- Choose one between task\_id and external\_task\_id for querying - ---- - -## Query Task (List) - -GET `/v1/videos/image2video` - -```bash -curl --request GET \ - --url 'https://api-singapore.klingai.com/v1/videos/image2video?pageNum=1&pageSize=30' \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in Error codes - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, to track requests and troubleshoot problems - "data": [ - { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) - "task_info": { // Task creation parameters - "external_task_id": "string" // Customer-defined task ID - }, - "task_result": { - "videos": [ - { - "id": "string", // Generated video ID; globally unique - "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) - "watermark_url": "string", // Watermarked video download URL, anti-leech format - "duration": "string" // Total video duration, unit: s (seconds) - } - ] - }, - "watermark_info": { - "enabled": boolean - }, - "final_unit_deduction": "string", // The deduction units of task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms - } - ] -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Query Parameters - -Page number - -- Value range: \[1, 1000\] - -Data volume per page - -- Value range: \[1, 500\] \ No newline at end of file diff --git a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 3.md b/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 3.md deleted file mode 100644 index 3049098..0000000 --- a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 3.md +++ /dev/null @@ -1,305 +0,0 @@ ---- -title: "Kling AI: Next-Gen AI Video & AI Image Generator" -source: "https://kling.ai/document-api/apiReference/model/multiImageToVideo" -author: -published: -created: 2026-04-24 -description: -tags: - - "clippings" ---- -## Create Task - -POST `/v1/videos/multi-image2video` - -```bash -curl --request POST \ - --url https://api-singapore.klingai.com/v1/videos/multi-image2video \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "model_name": "kling-v1-6", - "image_list": [ - { "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dog.png" }, - { "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dog_cloth.png" } - ], - "prompt": "A white Bichon Frise wearing a red Northeast-style floral cotton jacket, licking its paw", - "negative_prompt": "", - "mode": "pro", - "duration": "5", - "aspect_ratio": "16:9", - "callback_url": "", - "external_task_id": "" - }' -``` - -200 - -```json -{ - "code": 0, // Error code; Specific definitions can be found in "Error Code" - "message": "string", // Error message - "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems - "data": { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms - } -} -``` - -Generate video from multiple reference images (elements). - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Request Body - -Model Name - -Enum values：kling-v1-6 - -image\_listarrayRequired - -Reference Image List - -- Support up to 4 images, load with key:value format as follows: - -```json -"image_list":[ - { "image":"image_url" }, - { "image":"image_url" }, - { "image":"image_url" }, - { "image":"image_url" } -] -``` - -- Please directly upload the image with selected subject since there is no cropping logic on the API side - -- Supports image input as either Base64-encoded string or URL (ensure the URL is publicly accessible) - -- Important: When using Base64, do NOT add any prefix like `data:image/png;base64,`. Submit only the raw Base64 string. - -- Correct Base64 format: - -``` -iVBORw0KGgoAAAANSUhEUgAAAAUA... -``` - -- Incorrect Base64 format (with data: prefix): - -``` -data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA... -``` - -- Supported image formats:.jpg /.jpeg /.png - -- Image file size must not exceed 10MB. Image dimensions must be at least 300px. Aspect ratio must be between 1:2.5 and 2.5:1 - -▾Hide child attributes - -imagestringRequired - -Image URL or Base64 string - -promptstringRequired - -Positive text prompt - -- Cannot exceed 2500 characters - -negative\_promptstringOptional - -Negative text prompt - -- Cannot exceed 2500 characters - -Video generation mode - -Enum values：stdpro - -- std: Standard Mode, which is cost-effective - -- pro: Professional Mode, generates higher quality video output - -Different model versions and video modes have different support ranges. For details, see [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) - -Video Length, unit: s (seconds) - -Enum values：510 - -The aspect ratio of the generated video frame (width:height) - -Enum values：16:99:161:1 - -watermark\_infoobjectOptional - -Whether to generate watermarked results simultaneously - -- Defined by the enabled parameter, format: - -```json -"watermark_info": { "enabled": boolean } -``` - -- true: generate watermarked result, false: do not generate - -- Custom watermarks are not currently supported - -callback\_urlstringOptional - -The callback notification address for the result of this task. If configured, the server will actively notify when the task status changes - -- The specific message schema of the notification can be found in [Callback Protocol](https://kling.ai/document-api/apiReference/callbackProtocol) - -external\_task\_idstringOptional - -Customized Task ID - -- User-defined task ID. It will not override the system-generated task ID, but supports querying tasks by this ID - -- Please note that it must be unique for each user - ---- - -## Query Task (Single) - -GET `/v1/videos/multi-image2video/{id}` - -```bash -curl --request GET \ - --url https://api-singapore.klingai.com/v1/videos/multi-image2video/{task_id} \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error code; Specific definitions can be found in "Error Code" - "message": "string", // Error message - "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems - "data": { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status message, displays failure reason when task fails (such as content moderation triggers) - "task_info": { //Task creation parameters - "external_task_id": "string" //User-defined task ID - }, - "task_result": { - "videos": [ - { - "id": "string", // Generated video ID; globally unique - "url": "string", // URL for generating videos (Please note that for security purposes, generated images/videos will be deleted after 30 days. Please save them promptly.) - "watermark_url": "string", // Watermarked video download URL, anti-hotlinking format - "duration": "string" //Total video duration, unit: s (seconds) - } - ] - }, - "watermark_info": { - "enabled": boolean - }, - "final_unit_deduction": "string", // Final unit deduction for the task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Path Parameters - -task\_idstringOptional - -Task ID for Multi-Image to Video - -- Request path parameter, fill the value directly in the request path - -- You can choose to query by external\_task\_id or task\_id - -external\_task\_idstringOptional - -Customized Task ID for Multi-Image to Video - -- Request path parameter, fill the value directly in the request path - -- The external\_task\_id filled in when creating the task. You can choose to query by external\_task\_id or task\_id - ---- - -## Query Task (List) - -GET `/v1/videos/multi-image2video` - -```bash -curl --request GET \ - --url 'https://api-singapore.klingai.com/v1/videos/multi-image2video?pageNum=1&pageSize=30' \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error code; Specific definitions can be found in "Error Code" - "message": "string", // Error message - "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems - "data": [ - { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status message, displays failure reason when task fails (such as content moderation triggers) - "task_info": { //Task creation parameters - "external_task_id": "string" //User-defined task ID - }, - "task_result": { - "videos": [ - { - "id": "string", // Generated video ID; globally unique - "url": "string", // URL for generating videos (Please note that for security purposes, generated images/videos will be deleted after 30 days. Please save them promptly.) - "watermark_url": "string", // Watermarked video download URL, anti-hotlinking format - "duration": "string" //Total video duration, unit: s (seconds) - } - ] - }, - "watermark_info": { - "enabled": boolean - }, - "final_unit_deduction": "string", // Final unit deduction for the task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms - } - ] -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Query Parameters - -Page number - -- Value range: \[1, 1000\] - -Number of items per page - -- Value range: \[1, 500\] \ No newline at end of file diff --git a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 4.md b/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 4.md deleted file mode 100644 index 70c5242..0000000 --- a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 4.md +++ /dev/null @@ -1,331 +0,0 @@ ---- -title: "Kling AI: Next-Gen AI Video & AI Image Generator" -source: "https://kling.ai/document-api/apiReference/model/motionControl" -author: -published: -created: 2026-04-24 -description: -tags: - - "clippings" ---- -## Create Task - -POST `/v1/videos/motion-control` - -```bash -curl --request POST \ - --url https://api-singapore.klingai.com/v1/videos/motion-control \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json; charset=utf-8' \ - --data-raw '{ - "model_name": "kling-v2-6", - "image_url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-3.ng.png", - "prompt": "The girl is wearing a loose gray T-shirt and denim shorts", - "video_url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dance.mp4", - "keep_original_sound": "yes", - "character_orientation": "image", - "mode": "pro", - "callback_url": "", - "external_task_id": "xxx" - }' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in "Error Code" - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems - "data": { - "task_id": "string", // Task ID, generated by the system - "task_info": { //Task creation parameters - "external_task_id": "string" //Customer-defined task ID - }, - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Request Body - -Model Name - -Enum values：kling-v2-6kling-v3 - -promptstringOptional - -Text prompt, can include positive and negative descriptions - -- Can add elements to the scene, achieve camera movement effects, etc. See [Kling "Motion Control" User Guide](https://kling.ai/quickstart/motion-control-user-guide) - -- Cannot exceed 2500 characters - -image\_urlstringRequired - -Reference image. Characters, background and other elements in generated video will follow this reference. - -- Video content requirements: - - Character proportions should match the reference motion as much as possible; avoid driving half-body characters with full-body motions - - Character should show clear upper body or full body including limbs and head, avoid occlusion - - Avoid extreme orientations (upside down, lying flat, etc.). Character should occupy sufficient screen area - - Supports realistic/stylized characters (including humans/humanoid animals/some pure animals/some humanoid body proportion characters) - -- Supports image Base64 encoding or image URL (ensure accessibility) - -- Important: When using Base64, do NOT add any prefix like `data:image/png;base64,`. Submit only the raw Base64 string. - -- Correct Base64 format: - -``` -iVBORw0KGgoAAAANSUhEUgAAAAUA... -``` - -- Incorrect Base64 format (with data: prefix): - -``` -data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA... -``` - -- Supported image formats:.jpg /.jpeg /.png - -- File size: ≤10MB, dimensions: 300px ~ 65536px, aspect ratio: 1:2.5 ~ 2.5:1 - -video\_urlstringRequired - -URL of reference video. Character actions in generated video will follow this reference. - -- Video content requirements: - - Character should show clear upper body or full body including all limbs and head, avoid occlusion - - Recommend uploading single-person action video; for 2+ people, actions will be taken from the character with largest screen proportion - - Recommend using real person actions; some stylized characters/humanoid body proportions may work - - Video should be single continuous shot with character always visible, avoid cuts or camera movements (will be truncated otherwise) - - Avoid overly fast actions; relatively stable actions produce better results - -- Supported formats:.mp4 /.mov, file size: ≤100MB, dimensions: 340px ~ 3850px. Validation failures will return error codes. - -- Duration limits: minimum 3 seconds, maximum depends on character\_orientation: - - When character\_orientation is "video": maximum 30 seconds - - When character\_orientation is "image": maximum 10 seconds - -- The duration range of the uploaded motion reference is from 3 to 30 seconds, in which the generated video length will align with the duration of the uploaded video. If motions are complex or fast-paced, there is a chance that the output may be shorter than the uploaded video duration, as the model can only extract the valid action duration for generation. The minimum extractable continuous action duration is 3 seconds. Please note that in such cases, the consumed credits cannot be refunded. It is recommended to adjust the complexity and speed of the actions accordingly. - -- System will validate video content and return error codes if issues are found - -element\_listarrayOptional - -Reference Element List based on element ID configuration - -- Load with key:value format as follows: - -```json -"element_list":[ - { "element_id": 829836802793406551 } -] -``` - -- When referencing the element, the generated video can only temporarily refer to the orientation of the person in the video. - -- Currently, only one element can be introduced. - -▾Hide child attributes - -element\_idlongRequired - -Element ID from element library - -Whether to keep the original sound of the video - -Enum values：yesno - -character\_orientationstringRequired - -Character orientation in generated video, can match image or video - -Enum values：imagevideo - -- image: Match character orientation in the image; reference video duration must not exceed 10 seconds - -- video: Match character orientation in the video; reference video duration must not exceed 30 seconds - -- When referencing the element, the generated video can only temporarily refer to the orientation of the person in the video. - -modestringRequired - -Video generation mode - -Enum values：stdpro - -- std: Standard Mode - basic mode, cost-effective - -- pro: Professional Mode (High Quality) - high performance mode, better video quality - -Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. - -watermark\_infoobjectOptional - -Whether to generate watermarked results simultaneously - -- Defined by the enabled parameter, format: - -```json -"watermark_info": { "enabled": boolean } -``` - -- true: generate watermarked result, false: do not generate - -- Custom watermarks are not currently supported - -callback\_urlstringOptional - -Callback notification URL for task result. If configured, server will notify when task status changes. - -- For specific message schema, see [Callback Protocol](https://kling.ai/document-api/apiReference/callbackProtocol) - -external\_task\_idstringOptional - -Customized Task ID - -- Will not overwrite system-generated task ID, but supports querying task by this ID - -- Must be unique within a single user account - ---- - -## Query Task (Single) - -GET `/v1/videos/motion-control/{id}` - -```bash -curl --request GET \ - --url https://api-singapore.klingai.com/v1/videos/motion-control/{task_id} \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in "Error Code" - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems - "data": { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) - "task_info": { //Task creation parameters - "external_task_id": "string" //Customer-defined task ID - }, - "task_result": { - "videos": [ - { - "id": "string", // Generated video ID; globally unique - "url": "string", // URL for generating videos, anti-leech format (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) - "watermark_url": "string", // Watermarked video download URL, anti-leech format - "duration": "string" //Total video duration, unit: s (seconds) - } - ] - }, - "watermark_info": { - "enabled": boolean - }, - "final_unit_deduction": "string", // The deduction units of task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Path Parameters - -task\_idstringOptional - -Task ID for Motion Control. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying. - -external\_task\_idstringOptional - -Customized Task ID for Motion Control. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying. - ---- - -## Query Task (List) - -GET `/v1/videos/motion-control` - -```bash -curl --request GET \ - --url 'https://api-singapore.klingai.com/v1/videos/motion-control?pageNum=1&pageSize=30' \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in "Error Code" - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems - "data": [ - { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) - "task_info": { //Task creation parameters - "external_task_id": "string" //Customer-defined task ID - }, - "task_result": { - "videos": [ - { - "id": "string", // Generated video ID; globally unique - "url": "string", // URL for generating videos, anti-leech format (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) - "watermark_url": "string", // Watermarked video download URL, anti-leech format - "duration": "string" //Total video duration, unit: s (seconds) - } - ] - }, - "watermark_info": { - "enabled": boolean - }, - "final_unit_deduction": "string", // The deduction units of task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms - } - ] -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Query Parameters - -Page number - -- Value range: \[1, 1000\] - -Data volume per page - -- Value range: \[1, 500\] \ No newline at end of file diff --git a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 5.md b/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 5.md deleted file mode 100644 index 5b9b5d5..0000000 --- a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 5.md +++ /dev/null @@ -1,794 +0,0 @@ ---- -title: "Kling AI: Next-Gen AI Video & AI Image Generator" -source: "https://kling.ai/document-api/apiReference/model/multiElements" -author: -published: -created: 2026-04-24 -description: -tags: - - "clippings" ---- -## Initialize Video for Editing - -POST `/v1/videos/multi-elements/init-selection` - -```bash -curl --request POST \ - --url https://api-singapore.klingai.com/v1/videos/multi-elements/init-selection \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "video_id": "", - "video_url": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/animals-output-5s.mp4" - }' -``` - -200 - -```json -{ - "code": 0, // Error code; Specific definitions can be found in "Error Code" - "message": "string", // Error message - "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting - "data": { - "status": 0, // Rejection code, non-zero indicates recognition failure - "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours - "final_unit_deduction": "string", // The deduction units of task - "fps": 30.0, // Frame rate of parsed video, required when fetching selection preview video - "original_duration": 1000, // Duration of parsed video, required when creating task - "width": 720, // Width of parsed video, currently unused - "height": 1280, // Height of parsed video, currently unused - "total_frame": 300, // Total frame count of parsed video, required when creating task - "normalized_video": "url" // URL of initialized video -} -``` - -💡 - -Initialize the original video before using Multi-elements feature. When replacing or removing elements within the existing video, the relevant elements need to be marked in the video beforehand. - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Request Body - -video\_idstringOptional - -The ID of the video generated by the Kling AI - -- Only videos generated within the last 30 days are supported - -- Only supports videos with a duration of ≥2 seconds and ≤5 seconds, or ≥7 seconds and ≤10 seconds - -video\_urlstringOptional - -Get link for uploaded video - -- Only.mp4/.mov formats are supported - -- Only supports videos with a duration of ≥2 seconds and ≤5 seconds, or ≥7 seconds and ≤10 seconds - -- Video resolution must be between 720px and 2160px (inclusive) in both width and height - -- Only supports videos with frame rates of 24, 30, or 60 fps - ---- - -## Add Video Selection Area - -POST `/v1/videos/multi-elements/add-selection` - -```bash -curl --request POST \ - --url https://api-singapore.klingai.com/v1/videos/multi-elements/add-selection \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "session_id": "847570360458960960", - "frame_index": 0, - "points": [ - { - "x": 0.7738498789346246, - "y": 0.297142857142857 - } - ] - }' -``` - -200 - -```json -{ - "code": 0, // Error code; Specific definitions can be found in "Error Code" - "message": "string", // Error message - "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting - "data": { - "status": 0, // Rejection code, non-zero indicates recognition failure - "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours - "final_unit_deduction": "string", // The deduction units of task - "res": { - "frame_index": 0, - "rle_mask_list": [{ - "object_id": 0, - "rle_mask": { - "size": [720, 1280], - "counts": "string" - }, - "png_mask": { - "size": [720, 1280], - "base64": "string" - } - }] - } - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Request Body - -session\_idstringRequired - -Session ID, generated during the video initialization task and remains unchanged during editing operations - -frame\_indexintRequired - -Frame Number - -- A maximum of 10 frames can be marked. That is, up to 10 frames can be used to define selection areas in the video - -- Only supports marking 1 frame at a time - -pointsarrayRequired - -Click Coordinates, represented by x and y - -- Value range: \[0, 1\], expressed as percentages; \[0, 1\] represents the top-left corner of the frame - -- Multiple points can be marked at once; up to 10 points can be marked on a single frame - -▾Hide child attributes - -xfloatRequired - -X coordinate \[0-1\] - -yfloatRequired - -Y coordinate \[0-1\] - -### Sample Code - -#### Decoding Image Segmentation Result - -```typescript -export type RLEObject = { - size: [h: number, w: number] - counts: string -} -type RLE = { - h: number - w: number - m: number - binaries: number[] -} -export function decode(rleObj: RLEObject) { - const [h, w] = rleObj.size - const R: RLE = { h, w, m: 0, binaries: [0] } - rleFrString(R, rleObj.counts) - const unitArray = new Uint8Array(h * w) - rleDecode(R, unitArray) - return unitArray -} -function rleDecode(R: RLE, M: Uint8Array) { - let j - let k - let p = 0 - let v = false - for (j = 0; j < R.m; j++) { - for (k = 0; k < R.binaries[j]; k++) { - const x = Math.floor(p / R.h) - const y = p % R.h - M[y * R.w + x] = v === false ? 0 : 1 // Note: y * width + x indicates row-major (horizontal) layout. - p++ - } - v = !v - } -} -function rleFrString(R: RLE, s: string) { - let m = 0 - let p = 0 - let k - let x - let more - const binaries = [] - while (s[p]) { - x = 0 - k = 0 - more = 1 - while (more) { - const c = s.charCodeAt(p) - 48 - x |= (c & 0x1f) << (5 * k) - more = c & 0x20 - p++ - k++ - if (!more && c & 0x10) { - x |= -1 << (5 * k) - } - } - if (m > 2) { - x += binaries[m - 2] - } - binaries[m++] = x - } - R.m = m - R.binaries = binaries -} -``` - -#### Rendering the Segmentation Mask Layer - -```typescript -// height refers to the video height and width refers to the video width -function drawMask(rleMask: string, height: number, width: number) { - if (!canvasRef.value) return - const ctx = canvasRef.value.getContext('2d') - if (!ctx) return - - const decodeData = decode({ counts: rleMask, size: [height, width] }) - const imageData = ctx.createImageData(width, height) - for (let y = 0; y < height; y++) { - for (let x = 0; x < width; x++) { - const index = y * width + x - if (decodeData[index]) { - const imageIndex = index * 4 - // Set pixel color: red, green, blue, alpha - imageData.data[imageIndex] = 116 // red - imageData.data[imageIndex + 1] = 255 // green - imageData.data[imageIndex + 2] = 82 // blue - imageData.data[imageIndex + 3] = 163 // alpha - } - } - } - ctx.putImageData(imageData, 0, 0) -} -``` - ---- - -## Delete Video Selection Area - -POST `/v1/videos/multi-elements/delete-selection` - -```bash -curl --request POST \ - --url https://api-singapore.klingai.com/v1/videos/multi-elements/delete-selection \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "session_id": "847570360458960960", - "frame_index": 0, - "points": [ - { - "x": 0.7738498789346246, - "y": 0.297142857142857 - } - ] - }' -``` - -200 - -```json -{ - "code": 0, // Error code; Specific definitions can be found in "Error Code" - "message": "string", // Error message - "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting - "data": { - "status": 0, // Rejection code, non-zero indicates recognition failure - "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours - "final_unit_deduction": "string", // The deduction units of task - "res": { - "frame_index": 0, - "rle_mask_list": [{ - "object_id": 0, - "rle_mask": { - "size": [720, 1280], - "counts": "string" - }, - "png_mask": { - "size": [720, 1280], - "base64": "string" - } - }] - } - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Request Body - -session\_idstringRequired - -Session ID, generated during the video initialization task and remains unchanged during editing operations - -frame\_indexintRequired - -Frame Number - -pointsarrayRequired - -Click Coordinates to delete, represented by x and y - -- Value range: \[0, 1\], expressed as percentages; \[0, 1\] represents the top-left corner of the frame - -- Multiple points can be provided at once - -- Coordinates must exactly match those used when adding the video selection area - -▾Hide child attributes - -xfloatRequired - -X coordinate \[0-1\] - -yfloatRequired - -Y coordinate \[0-1\] - ---- - -## Clear Video Selection - -POST `/v1/videos/multi-elements/clear-selection` - -```bash -curl --request POST \ - --url https://api-singapore.klingai.com/v1/videos/multi-elements/clear-selection \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "session_id": "847570360458960960" - }' -``` - -200 - -```json -{ - "code": 0, // Error code; Specific definitions can be found in "Error Code" - "message": "string", // Error message - "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting - "data": { - "status": 0, // Rejection code, non-zero indicates recognition failure - "session_id": "id" // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours - "final_unit_deduction": "string", // The deduction units of task - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Request Body - -session\_idstringRequired - -Session ID, generated during the video initialization task and remains unchanged during editing operations - ---- - -## Preview Video with Selected Areas - -POST `/v1/videos/multi-elements/preview-selection` - -```bash -curl --request POST \ - --url https://api-singapore.klingai.com/v1/videos/multi-elements/preview-selection \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "session_id": "847570360458960960" - }' -``` - -200 - -```json -{ - "code": 0, // Error code; Specific definitions can be found in "Error Code" - "message": "string", // Error message - "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting - "data": { - "status": 0, // Rejection code, non-zero indicates recognition failure - "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours - "final_unit_deduction": "string", // The deduction units of task - "res": { - "video": "url", // Video with mask - "video_cover": "url", // Cover image of video with mask - "tracking_output": "url" // Mask result for each frame in image segmentation results - } - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Request Body - -session\_idstringRequired - -Session ID, generated during the video initialization task and remains unchanged during editing operations - ---- - -## Create Task - -POST `/v1/videos/multi-elements` - -```bash -curl --request POST \ - --url https://api-singapore.klingai.com/v1/videos/multi-elements \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "model_name": "kling-v1-6", - "session_id": "847570360458960960", - "edit_mode": "removal", - "image_list": [], - "prompt": "Delete the chick from <<>>", - "negative_prompt": "", - "mode": "std", - "duration": "5", - "callback_url": "", - "external_task_id": "" - }' -``` - -200 - -```json -{ - "code": 0, // Error code; Specific definitions can be found in "Error Code" - "message": "string", // Error message - "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting - "data": { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_info": { - "external_task_id": "string" // User-defined task ID - }, - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Request Body - -Model Name - -Enum values：kling-v1-6 - -session\_idstringRequired - -Session ID, generated during the video initialization task and remains unchanged during editing operations - -edit\_modestringRequired - -Operation Type - -Enum values：additionswapremoval - -- addition: Add an element - -- swap: Replace an element - -- removal: Remove an element - -image\_listarrayOptional - -Cropped Reference Images - -- For adding video elements: This parameter is required; upload 1–2 images - -- For editing (swapping) video elements: This parameter is required; upload 1 image only - -- For deleting video elements: This parameter is not required - -- Use key:value format as follows: - -```json -"image_list":[ - { "image":"image_url" }, - { "image":"image_url" } -] -``` - -- The API does not perform cropping, please upload images with subjects already cropped - -- Supports image input as either Base64-encoded string or URL (ensure the URL is publicly accessible) - -- Important: When using Base64, do NOT add any prefix like `data:image/png;base64,`. Submit only the raw Base64 string. - -- Correct Base64 format: - -``` -iVBORw0KGgoAAAANSUhEUgAAAAUA... -``` - -- Incorrect Base64 format (with data: prefix): - -``` -data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA... -``` - -- Supported image formats:.jpg /.jpeg /.png - -- Image file size must not exceed 10MB. Image dimensions must be at least 300px. Aspect ratio must be between 1:2.5 and 2.5:1 - -▾Hide child attributes - -imagestringRequired - -Image URL or Base64 string - -promptstringRequired - -Positive Prompt - -- Use the format <<>> to explicitly refer to a specific video or image, such as <<>> or <<>> - -- To ensure optimal results, the prompt must include references to the video and image(s) required for the editing - -- Must not exceed 2,500 characters - -💡 - -**Recommended Prompt Templates:** - -**Adding Elements:** - -- EN: Using the context of <<>>, seamlessly add \[x\] from <<>> -- ZH: 基于<<>>中的原始内容，以自然生动的方式，将<<>>中的【】，融入<<>>的【】 - -**Replacing Elements:** - -- EN: swap \[x\] from <<>> for \[x\] from <<>> -- ZH: 使用<<>>中的【】，替换<<>>中的【】 - -**Removing Elements:** - -- EN: Delete \[x\] from <<>> -- ZH: 删除<<>>中的【】 - -Note: \[x\] or 【】 are placeholders where you should fill in specific content. - -negative\_promptstringOptional - -Negative Prompt - -- Must not exceed 2,500 characters - -Video Generation Mode - -Enum values：stdpro - -- std: Standard mode, basic rendering, cost-effective - -- pro: Professional mode, high-quality, enhanced rendering, better video output quality - -Video Duration (in seconds) - -Enum values：510 - -- Only 5-second and 10-second videos are supported - -- To generate a 5-second video, the input video must be ≥2 seconds and ≤5 seconds - -- To generate a 10-second video, the input video must be ≥7 seconds and ≤10 seconds - -watermark\_infoobjectOptional - -Whether to generate watermarked results simultaneously - -- Defined by the enabled parameter, format: - -```json -"watermark_info": { "enabled": boolean } -``` - -- true: generate watermarked result, false: do not generate - -- Custom watermarks are not currently supported - -callback\_urlstringOptional - -Callback URL for Task Result Notification. If configured, the server will actively send notifications when the task status changes - -- For the message schema, refer to the [Callback Protocol](https://kling.ai/document-api/apiReference/callbackProtocol) - -external\_task\_idstringOptional - -Custom Task ID - -- A user-defined task ID; it will not overwrite the system-generated task ID, but can be used to query the task - -- Please ensure uniqueness of the task ID within a single user account - ---- - -## Query Task (Single) - -GET `/v1/videos/multi-elements/{id}` - -```bash -curl --request GET \ - --url https://api-singapore.klingai.com/v1/videos/multi-elements/{task_id} \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error code; Specific definitions can be found in "Error Code" - "message": "string", // Error message - "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting - "data": { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status message, displays failure reason when task fails (e.g., triggered platform content moderation) - "task_info": { // Task creation parameters - "external_task_id": "string" // User-defined task ID - }, - "task_result": { - "videos": [ - { - "id": "string", // Generated video ID, globally unique - "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours - "url": "string", // URL of generated video (Note: For security purposes, generated images/videos will be deleted after 30 days, please save them promptly) - "watermark_url": "string", // Watermarked video download URL, anti-hotlinking format - "duration": "string" // Total video duration, unit: s - } - ] - }, - "watermark_info": { - "enabled": boolean - }, - "final_unit_deduction": "string", // Final unit deduction for the task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Path Parameters - -task\_idstringOptional - -Task ID for Multi-Elements video editing - -- Request path parameter, fill the value directly in the request path - -- You can choose to query by external\_task\_id or task\_id - -external\_task\_idstringOptional - -Custom Task ID for Multi-Elements video editing - -- The external\_task\_id filled in when creating the task. You can choose to query by external\_task\_id or task\_id - ---- - -## Query Task (List) - -GET `/v1/videos/multi-elements` - -```bash -curl --request GET \ - --url 'https://api-singapore.klingai.com/v1/videos/multi-elements?pageNum=1&pageSize=30' \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error code; Specific definitions can be found in "Error Code" - "message": "string", // Error message - "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting - "data": [ - { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status message, displays failure reason when task fails (e.g., triggered platform content moderation) - "task_info": { // Task creation parameters - "external_task_id": "string" // User-defined task ID - }, - "task_result": { - "videos": [ - { - "id": "string", // Generated video ID, globally unique - "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours - "url": "string", // URL of generated video (Note: For security purposes, generated images/videos will be deleted after 30 days, please save them promptly) - "watermark_url": "string", // Watermarked video download URL, anti-hotlinking format - "duration": "string" // Total video duration, unit: s - } - ] - }, - "watermark_info": { - "enabled": boolean - }, - "final_unit_deduction": "string", // Final unit deduction for the task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms - } - ] -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Query Parameters - -Page number - -- Value range: \[1, 1000\] - -Number of items per page - -- Value range: \[1, 500\] \ No newline at end of file diff --git a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 6.md b/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 6.md deleted file mode 100644 index 6e3db25..0000000 --- a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 6.md +++ /dev/null @@ -1,252 +0,0 @@ ---- -title: "Kling AI: Next-Gen AI Video & AI Image Generator" -source: "https://kling.ai/document-api/apiReference/model/videoExtension" -author: -published: -created: 2026-04-24 -description: -tags: - - "clippings" ---- -## Create Task - -POST `/v1/videos/video-extend` - -```bash -curl --request POST \ - --url https://api-singapore.klingai.com/v1/videos/video-extend \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "prompt": "A puppy appears", - "video_id": "743211632612511839", - "negative_prompt": "", - "callback_url": "" - }' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in Error codes - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems - "data": { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_info":{ // Task creation parameters - "external_task_id": "string" // Customer-defined task ID - }, - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms - } -} -``` - -- Note 1: Video extension refers to extending the duration of text-to-video/image-to-video results. Each extension can add 4 to 5 seconds, and the model and mode used cannot be selected; they must be the same as the source video. -- Note 2: Videos that have been extended can be extended again, but the total video duration cannot exceed 3 minutes. - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Request Body - -video\_idstringRequired - -Video ID - -- Supports video IDs generated by the text-to-video, the image-to-video and the video extension interface (it cannot exceed 3 minutes). - -- Only videos generated by V1.0, V1.5, and V1.6 models are supported. - -> Please note that based on the current cleanup policy, videos will be cleared 30 days after generation, and extension will not be possible. - -promptstringOptional - -Text Prompt - -Cannot exceed 2500 characters - -negative\_promptstringOptional - -Negative text prompt - -Cannot exceed 2500 characters - -Prompt reference strength. The higher the value, the stronger the reference to the prompt. - -Value range: \[0, 1\] - -watermark\_infoobjectOptional - -Whether to generate watermarked results simultaneously - -- Defined by the enabled parameter, format: - -```json -"watermark_info": { "enabled": boolean } -``` - -- true: generate watermarked result, false: do not generate - -- Custom watermarks are not currently supported - -callback\_urlstringOptional - -The callback notification address for the task results. If configured, the server will actively notify when the task status changes. - -- For specific message schema, see [Callback Protocol](https://kling.ai/document-api/apiReference/callbackProtocol) - -external\_task\_idstringOptional - -Customized Task ID - -- User-defined task ID. It will not override the system-generated task ID, but supports querying tasks by this ID - -- Please note that it must be unique for each user - ---- - -## Query Task (Single) - -GET `/v1/videos/video-extend/{id}` - -```bash -curl --request GET \ - --url https://api-singapore.klingai.com/v1/videos/video-extend/{task_id} \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in Error codes - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems - "data": { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) - "task_info": { - "parent_video": { //Parameters information when the task is created - "id": "string", //Video ID before the extension；globally unique - "url": "string", //URL for generating images(To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) - "duration": "string" //Original video duration, unit: s (seconds) - }, - "external_task_id": "string" // Customer-defined task ID - }, - "task_result": { - "videos": [ - { - "id": "string", // Generated video ID; globally unique, will be cleared after 30 days - "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) - "watermark_url": "string", // Watermarked video download URL, anti-leech format - "duration": "string" //Total video duration, unit: s (seconds) - } - ] - }, - "watermark_info": { - "enabled": boolean - }, - "final_unit_deduction": "string", // The deduction units of task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Path Parameters - -task\_idstringOptional - -Task ID for Video Generation. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying. - -external\_task\_idstringOptional - -Customized Task ID for Video Generation. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying. - ---- - -## Query Task (List) - -GET `/v1/videos/video-extend` - -```bash -curl --request GET \ - --url 'https://api-singapore.klingai.com/v1/videos/video-extend?pageNum=1&pageSize=30' \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in Error codes - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems - "data": [ - { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) - "task_info": { - "parent_video": { //Parameters information when the task is created - "id": "string", //Video ID before the extension；globally unique - "url": "string", //URL for generating images(To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) - "duration": "string" //Original video duration, unit: s (seconds) - }, - "external_task_id": "string" // Customer-defined task ID - }, - "task_result": { - "videos": [ - { - "id": "string", // Generated video ID; globally unique, will be cleared after 30 days - "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) - "watermark_url": "string", // Watermarked video download URL, anti-leech format - "duration": "string" //Total video duration, unit: s (seconds) - } - ] - }, - "watermark_info": { - "enabled": boolean - }, - "final_unit_deduction": "string", // The deduction units of task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms - } - ] -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Query Parameters - -Page number - -Value range: \[1, 1000\] - -Number of items per page - -Value range: \[1, 500\] \ No newline at end of file diff --git a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 7.md b/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 7.md deleted file mode 100644 index 1f0c29d..0000000 --- a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator 7.md +++ /dev/null @@ -1,380 +0,0 @@ ---- -title: "Kling AI: Next-Gen AI Video & AI Image Generator" -source: "https://kling.ai/document-api/apiReference/model/lipSync" -author: -published: -created: 2026-04-24 -description: -tags: - - "clippings" ---- -## Identify Face - -POST `/v1/videos/identify-face` - -```bash -curl --request POST \ - --url https://api-singapore.klingai.com/v1/videos/identify-face \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "video_url": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/kling20260206mp4.mp4", - "video_id": "" - }' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in "Error Code" - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems - "data": { - "session_id": "id", // Session ID - "final_unit_deduction": "string", // The deduction units of task - "face_data": [ //Face data list - { - "face_id": "string", // Face ID - "face_image": "url", // Face image URL - "start_time": 0, // Face appearance start time, unit: ms - "end_time": 5200 //Face appearance end time, unit: ms - } - ] - } -} -``` - -Identify faces in the video for lip-sync processing. - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Request Body - -video\_idstringOptional - -The ID of the video generated by Kling AI - -- Used to specify the video and determine whether it can be used for lip-sync services. - -- This parameter and 'video\_url' are mutually exclusive—only one can be filled, and neither can be left empty. - -- Only supports videos generated within the last 30 days with a duration of no more than 60 seconds. - -video\_urlstringOptional - -The URL of the video - -- Used to specify the video and determine whether it can be used for lip-sync services. - -- This parameter and 'video\_id' are mutually exclusive—only one can be filled, and neither can be left empty. - -- Supported video formats:.mp4/.mov, file size ≤100MB, duration 2s–60s, resolution 720p or 1080p, with both width and height between 512px–2160px. If validation fails, an error code will be returned. - -- The system checks video content—if issues are detected, an error code will be returned. - ---- - -## Create Task - -POST `/v1/videos/advanced-lip-sync` - -```bash -curl --request POST \ - --url https://api-singapore.klingai.com/v1/videos/advanced-lip-sync \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "session_id": "850508686686064678", - "face_choose": [ - { - "face_id": "0", - "sound_file": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/go-to-world.mp3", - "sound_insert_time": 1000, - "sound_start_time": 0, - "sound_end_time": 3000, - "sound_volume": 2, - "original_audio_volume": 2 - } - ], - "external_task_id": "", - "callback_url": "" - }' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in "Error Code" - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems - "data": { - "task_id": "string", // Task ID, generated by the system - "task_info": { //Task creation parameters - "external_task_id": "string" //User-defined task ID - }, - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Request Body - -session\_idstringRequired - -Session ID generated during the identify face API. It remains unchanged during the selection/editing process. - -face\_choosearrayRequired - -Specified Face for Lip-Sync - -- Includes Face ID, lip movement reference data, etc. - -- Currently only supports one person lip-sync. - -▾Hide child attributes - -face\_idstringRequired - -Face ID - -- Returned by the facial recognition interface. - -audio\_idstringOptional - -Sound ID Generated via TTS API - -- Only supports audio generated within the last 30 days with a duration of no less than 2 seconds and no more than 60 seconds. - -- Either audio\_id or sound\_file must be provided (mutually exclusive; cannot be empty or both populated). - -sound\_filestringOptional - -Sound File - -- Supports Base64-encoded audio or accessible audio URL. - -- Accepted formats:.mp3/.wav/.m4a/.aac (max 5MB). Format mismatches or oversized files will return error codes. - -- Only supports audio with a duration of no less than 2 seconds and no more than 60 seconds. - -- Either audio\_id or sound\_file must be provided (mutually exclusive; cannot be empty or both populated). - -- The system will verify the audio content and return error codes if there are any problems. - -sound\_start\_timelongRequired - -Time point to start cropping sound - -- Based on the original sound start time, the start time is 0'0", units: ms - -- The sound before the starting point will be cropped, and the cropped sound must not be shorter than 2 seconds. - -sound\_end\_timelongRequired - -Time point to stop cropping sound - -- Based on the original sound start time, the start time is 0'0", units: ms - -- The sound after the end point will be cropped, and the cropped sound must not be shorter than 2 seconds. - -- The end point time shouldn't be later than the total duration of the original sound. - -sound\_insert\_timelongRequired - -The time for inserting cropped sound - -- Based on the original video start time, the start time is 0'0", units: ms - -- The time range for inserting sound should overlap with the face's lip-sync time interval for at least 2 seconds. - -- The start time for inserting sound must not be earlier than the start time of the video, and the end time for inserting sound must not be later than the end time of the video. - -Volume Controls (higher values = louder) - -- Value range: \[0, 2\] - -Original video volume (higher values = louder) - -- Value range: \[0, 2\] - -- No effect if source video is silent. - -watermark\_infoobjectOptional - -Whether to generate watermarked results simultaneously - -- Defined by the enabled parameter, format: - -```json -"watermark_info": { "enabled": boolean } -``` - -- true: generate watermarked result, false: do not generate - -- Custom watermarks are not currently supported - -external\_task\_idstringOptional - -Custom Task ID - -- User-defined task ID. It will not override the system-generated task ID, but supports querying tasks by this ID. - -- Please note that uniqueness must be ensured for each user. - -callback\_urlstringOptional - -The callback notification address for the result of this task. If configured, the server will actively notify when the task status changes. - -- For specific message schema, see [Callback Protocol](https://kling.ai/document-api/apiReference/callbackProtocol) - ---- - -## Query Task (Single) - -GET `/v1/videos/advanced-lip-sync/{id}` - -```bash -curl --request GET \ - --url https://api-singapore.klingai.com/v1/videos/advanced-lip-sync/{task_id} \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in "Error Code" - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems - "data": { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status message, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) - "task_info": { //Task creation parameters - "parent_video": { //Original video information - "id": "string", // Original video ID - "url": "string", // Original video URL - "duration": "string" //Original video duration, unit: s - } - }, - "task_result": { //Task result - "videos": [ //Generated video list - { - "id": "string", // Generated video ID; globally unique - "url": "string", // URL for generating videos (Please note that for security purposes, generated images/videos will be deleted after 30 days. Please save them promptly.) - "watermark_url": "string", // Watermarked video download URL, anti-hotlinking format - "duration": "string" //Total video duration, unit: s - } - ] - }, - "watermark_info": { - "enabled": boolean //Whether watermark is enabled - }, - "final_unit_deduction": "string", // The deduction units of task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms - } -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Path Parameters - -task\_idstringOptional - -Task ID for Video Generation - Lip-Sync. Fill the value directly in the request path. - ---- - -## Query Task (List) - -GET `/v1/videos/advanced-lip-sync` - -```bash -curl --request GET \ - --url 'https://api-singapore.klingai.com/v1/videos/advanced-lip-sync?pageNum=1&pageSize=30' \ - --header 'Authorization: Bearer ' -``` - -200 - -```json -{ - "code": 0, // Error codes; Specific definitions can be found in "Error Code" - "message": "string", // Error information - "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems - "data": [ - { - "task_id": "string", // Task ID, generated by the system - "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed - "task_status_msg": "string", // Task status message, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) - "task_info": { //Task creation parameters - "parent_video": { //Original video information - "id": "string", // Original video ID - "url": "string", // Original video URL - "duration": "string" //Original video duration, unit: s - } - }, - "task_result": { //Task result - "videos": [ //Generated video list - { - "id": "string", // Generated video ID; globally unique - "url": "string", // URL for generating videos (Please note that for security purposes, generated images/videos will be deleted after 30 days. Please save them promptly.) - "watermark_url": "string", // Watermarked video download URL, anti-hotlinking format - "duration": "string" //Total video duration, unit: s - } - ] - }, - "watermark_info": { - "enabled": boolean //Whether watermark is enabled - }, - "final_unit_deduction": "string", // The deduction units of task - "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms - "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms - } - ] -} -``` - -### Request Header - -Data Exchange Format - -AuthorizationstringRequired - -Authentication information, refer to API authentication - -### Query Parameters - -Page number - -- Value range: \[1, 1000\] - -Number of items per page - -- Value range: \[1, 500\] \ No newline at end of file diff --git a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator.md b/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator.md index 3ee367a..f1c3737 100644 --- a/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator.md +++ b/raw/_processed/Kling AI Next-Gen AI Video & AI Image Generator.md @@ -40,4 +40,1061 @@ tags:

Model

kling-v1

kling-v1-5

kling-v1-6

Image to Video

kling-v1-6

Text to Video

kling-v2 Master

Mode

STD

PRO

STD

PRO

STD

PRO

STD

PRO

-

Resolution

720p

720p

720p

1080p

720p

1080p

720p

1080p

720p

Frame Rate

30fps

30fps

30fps

30fps

30fps

30fps

24fps

24fps

24fps

-

Model

kling-v2-1

Image to Video

kling-v2-1 Master

kling-v2-5

Image to Video

kling-v2-5

Text to Video

Mode

STD

PRO

-

PRO

PRO

Resolution

720p

1080p

1080p

1080p

1080p

Frame Rate

24fps

24fps

24fps

24fps

24fps

\ No newline at end of file +

Model

kling-v2-1

Image to Video

kling-v2-1 Master

kling-v2-5

Image to Video

kling-v2-5

Text to Video

Mode

STD

PRO

-

PRO

PRO

Resolution

720p

1080p

1080p

1080p

1080p

Frame Rate

24fps

24fps

24fps

24fps

24fps

+source: "https://kling.ai/document-api/apiReference/model/lipSync" +## Identify Face +POST `/v1/videos/identify-face` +```bash +curl --request POST \ + --url https://api-singapore.klingai.com/v1/videos/identify-face \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "video_url": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/kling20260206mp4.mp4", + "video_id": "" + }' +``` +200 +```json +{ + "code": 0, // Error codes; Specific definitions can be found in "Error Code" + "message": "string", // Error information + "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems + "data": { + "session_id": "id", // Session ID + "final_unit_deduction": "string", // The deduction units of task + "face_data": [ //Face data list + { + "face_id": "string", // Face ID + "face_image": "url", // Face image URL + "start_time": 0, // Face appearance start time, unit: ms + "end_time": 5200 //Face appearance end time, unit: ms + } + ] + } +} +``` +Identify faces in the video for lip-sync processing. +### Request Header +Data Exchange Format +AuthorizationstringRequired +Authentication information, refer to API authentication +### Request Body +video\_idstringOptional +The ID of the video generated by Kling AI +- Used to specify the video and determine whether it can be used for lip-sync services. +- This parameter and 'video\_url' are mutually exclusive—only one can be filled, and neither can be left empty. +- Only supports videos generated within the last 30 days with a duration of no more than 60 seconds. +video\_urlstringOptional +The URL of the video +- Used to specify the video and determine whether it can be used for lip-sync services. +- This parameter and 'video\_id' are mutually exclusive—only one can be filled, and neither can be left empty. +- Supported video formats:.mp4/.mov, file size ≤100MB, duration 2s–60s, resolution 720p or 1080p, with both width and height between 512px–2160px. If validation fails, an error code will be returned. +- The system checks video content—if issues are detected, an error code will be returned. +## Create Task +POST `/v1/videos/advanced-lip-sync` +```bash +curl --request POST \ + --url https://api-singapore.klingai.com/v1/videos/advanced-lip-sync \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data '{ + "session_id": "850508686686064678", + "face_choose": [ + { + "face_id": "0", + "sound_file": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/go-to-world.mp3", + "sound_insert_time": 1000, + "sound_start_time": 0, + "sound_end_time": 3000, + "sound_volume": 2, + "original_audio_volume": 2 + } + ], + "external_task_id": "", + "callback_url": "" + }' +``` +200 +```json +{ + "code": 0, // Error codes; Specific definitions can be found in "Error Code" + "message": "string", // Error information + "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems + "data": { + "task_id": "string", // Task ID, generated by the system + "task_info": { //Task creation parameters + "external_task_id": "string" //User-defined task ID + }, + "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed + "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms + "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms + } +} +``` +### Request Header +Data Exchange Format +AuthorizationstringRequired +Authentication information, refer to API authentication +### Request Body +session\_idstringRequired +Session ID generated during the identify face API. It remains unchanged during the selection/editing process. +face\_choosearrayRequired +Specified Face for Lip-Sync +- Includes Face ID, lip movement reference data, etc. +- Currently only supports one person lip-sync. +▾Hide child attributes +face\_idstringRequired +Face ID +- Returned by the facial recognition interface. +audio\_idstringOptional +Sound ID Generated via TTS API +- Only supports audio generated within the last 30 days with a duration of no less than 2 seconds and no more than 60 seconds. +- Either audio\_id or sound\_file must be provided (mutually exclusive; cannot be empty or both populated). +sound\_filestringOptional +Sound File +- Supports Base64-encoded audio or accessible audio URL. +- Accepted formats:.mp3/.wav/.m4a/.aac (max 5MB). Format mismatches or oversized files will return error codes. +- Only supports audio with a duration of no less than 2 seconds and no more than 60 seconds. +- Either audio\_id or sound\_file must be provided (mutually exclusive; cannot be empty or both populated). +- The system will verify the audio content and return error codes if there are any problems. +sound\_start\_timelongRequired +Time point to start cropping sound +- Based on the original sound start time, the start time is 0'0", units: ms +- The sound before the starting point will be cropped, and the cropped sound must not be shorter than 2 seconds. +sound\_end\_timelongRequired +Time point to stop cropping sound +- Based on the original sound start time, the start time is 0'0", units: ms +- The sound after the end point will be cropped, and the cropped sound must not be shorter than 2 seconds. +- The end point time shouldn't be later than the total duration of the original sound. +sound\_insert\_timelongRequired +The time for inserting cropped sound +- Based on the original video start time, the start time is 0'0", units: ms +- The time range for inserting sound should overlap with the face's lip-sync time interval for at least 2 seconds. +- The start time for inserting sound must not be earlier than the start time of the video, and the end time for inserting sound must not be later than the end time of the video. +Volume Controls (higher values = louder) +- Value range: \[0, 2\] +Original video volume (higher values = louder) +- Value range: \[0, 2\] +- No effect if source video is silent. +watermark\_infoobjectOptional +Whether to generate watermarked results simultaneously +- Defined by the enabled parameter, format: +```json +"watermark_info": { "enabled": boolean } +``` +- true: generate watermarked result, false: do not generate +- Custom watermarks are not currently supported +external\_task\_idstringOptional +Custom Task ID +- User-defined task ID. It will not override the system-generated task ID, but supports querying tasks by this ID. +- Please note that uniqueness must be ensured for each user. +callback\_urlstringOptional +The callback notification address for the result of this task. If configured, the server will actively notify when the task status changes. +- For specific message schema, see [Callback Protocol](https://kling.ai/document-api/apiReference/callbackProtocol) +## Query Task (Single) +GET `/v1/videos/advanced-lip-sync/{id}` +```bash +curl --request GET \ + --url https://api-singapore.klingai.com/v1/videos/advanced-lip-sync/{task_id} \ + --header 'Authorization: Bearer ' +``` +200 +```json +{ + "code": 0, // Error codes; Specific definitions can be found in "Error Code" + "message": "string", // Error information + "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems + "data": { + "task_id": "string", // Task ID, generated by the system + "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed + "task_status_msg": "string", // Task status message, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) + "task_info": { //Task creation parameters + "parent_video": { //Original video information + "id": "string", // Original video ID + "url": "string", // Original video URL + "duration": "string" //Original video duration, unit: s + } + }, + "task_result": { //Task result + "videos": [ //Generated video list + { + "id": "string", // Generated video ID; globally unique + "url": "string", // URL for generating videos (Please note that for security purposes, generated images/videos will be deleted after 30 days. Please save them promptly.) + "watermark_url": "string", // Watermarked video download URL, anti-hotlinking format + "duration": "string" //Total video duration, unit: s + } + ] + }, + "watermark_info": { + "enabled": boolean //Whether watermark is enabled + }, + "final_unit_deduction": "string", // The deduction units of task + "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms + "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms + } +} +``` +### Request Header +Data Exchange Format +AuthorizationstringRequired +Authentication information, refer to API authentication +### Path Parameters +task\_idstringOptional +Task ID for Video Generation - Lip-Sync. Fill the value directly in the request path. +## Query Task (List) +GET `/v1/videos/advanced-lip-sync` +```bash +curl --request GET \ + --url 'https://api-singapore.klingai.com/v1/videos/advanced-lip-sync?pageNum=1&pageSize=30' \ + --header 'Authorization: Bearer ' +``` +200 +```json +{ + "code": 0, // Error codes; Specific definitions can be found in "Error Code" + "message": "string", // Error information + "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems + "data": [ + { + "task_id": "string", // Task ID, generated by the system + "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed + "task_status_msg": "string", // Task status message, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) + "task_info": { //Task creation parameters + "parent_video": { //Original video information + "id": "string", // Original video ID + "url": "string", // Original video URL + "duration": "string" //Original video duration, unit: s + } + }, + "task_result": { //Task result + "videos": [ //Generated video list + { + "id": "string", // Generated video ID; globally unique + "url": "string", // URL for generating videos (Please note that for security purposes, generated images/videos will be deleted after 30 days. Please save them promptly.) + "watermark_url": "string", // Watermarked video download URL, anti-hotlinking format + "duration": "string" //Total video duration, unit: s + } + ] + }, + "watermark_info": { + "enabled": boolean //Whether watermark is enabled + }, + "final_unit_deduction": "string", // The deduction units of task + "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms + "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms + } + ] +} +``` +### Request Header +Data Exchange Format +AuthorizationstringRequired +Authentication information, refer to API authentication +### Query Parameters +Page number +- Value range: \[1, 1000\] +Number of items per page +- Value range: \[1, 500\] + +source: "https://kling.ai/document-api/apiReference/model/multiImageToVideo" +POST `/v1/videos/multi-image2video` + --url https://api-singapore.klingai.com/v1/videos/multi-image2video \ + "model_name": "kling-v1-6", + "image_list": [ + { "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dog.png" }, + { "image": "https://p1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dog_cloth.png" } + "prompt": "A white Bichon Frise wearing a red Northeast-style floral cotton jacket, licking its paw", + "negative_prompt": "", + "mode": "pro", + "duration": "5", + "aspect_ratio": "16:9", + "callback_url": "", + "external_task_id": "" + "code": 0, // Error code; Specific definitions can be found in "Error Code" + "message": "string", // Error message +Generate video from multiple reference images (elements). +Model Name +Enum values：kling-v1-6 +image\_listarrayRequired +Reference Image List +- Support up to 4 images, load with key:value format as follows: +"image_list":[ + { "image":"image_url" }, + { "image":"image_url" }, + { "image":"image_url" }, + { "image":"image_url" } +] +- Please directly upload the image with selected subject since there is no cropping logic on the API side +- Supports image input as either Base64-encoded string or URL (ensure the URL is publicly accessible) +- Important: When using Base64, do NOT add any prefix like `data:image/png;base64,`. Submit only the raw Base64 string. +- Correct Base64 format: +iVBORw0KGgoAAAANSUhEUgAAAAUA... +- Incorrect Base64 format (with data: prefix): +data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA... +- Supported image formats:.jpg /.jpeg /.png +- Image file size must not exceed 10MB. Image dimensions must be at least 300px. Aspect ratio must be between 1:2.5 and 2.5:1 +imagestringRequired +Image URL or Base64 string +promptstringRequired +Positive text prompt +- Cannot exceed 2500 characters +negative\_promptstringOptional +Negative text prompt +- Cannot exceed 2500 characters +Video generation mode +Enum values：stdpro +- std: Standard Mode, which is cost-effective +- pro: Professional Mode, generates higher quality video output +Different model versions and video modes have different support ranges. For details, see [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) +Video Length, unit: s (seconds) +Enum values：510 +The aspect ratio of the generated video frame (width:height) +Enum values：16:99:161:1 +The callback notification address for the result of this task. If configured, the server will actively notify when the task status changes +- The specific message schema of the notification can be found in [Callback Protocol](https://kling.ai/document-api/apiReference/callbackProtocol) +Customized Task ID +- User-defined task ID. It will not override the system-generated task ID, but supports querying tasks by this ID +- Please note that it must be unique for each user +GET `/v1/videos/multi-image2video/{id}` + --url https://api-singapore.klingai.com/v1/videos/multi-image2video/{task_id} \ + "code": 0, // Error code; Specific definitions can be found in "Error Code" + "message": "string", // Error message + "task_status_msg": "string", // Task status message, displays failure reason when task fails (such as content moderation triggers) + "task_result": { + "videos": [ + "duration": "string" //Total video duration, unit: s (seconds) + "enabled": boolean + "final_unit_deduction": "string", // Final unit deduction for the task +Task ID for Multi-Image to Video +- Request path parameter, fill the value directly in the request path +- You can choose to query by external\_task\_id or task\_id +Customized Task ID for Multi-Image to Video +- Request path parameter, fill the value directly in the request path +- The external\_task\_id filled in when creating the task. You can choose to query by external\_task\_id or task\_id +GET `/v1/videos/multi-image2video` + --url 'https://api-singapore.klingai.com/v1/videos/multi-image2video?pageNum=1&pageSize=30' \ + "code": 0, // Error code; Specific definitions can be found in "Error Code" + "message": "string", // Error message + "task_status_msg": "string", // Task status message, displays failure reason when task fails (such as content moderation triggers) + "external_task_id": "string" //User-defined task ID + "task_result": { + "videos": [ + "duration": "string" //Total video duration, unit: s (seconds) + "enabled": boolean + "final_unit_deduction": "string", // Final unit deduction for the task + +source: "https://kling.ai/document-api/apiReference/model/imageToVideo" +POST `/v1/videos/image2video` +curl --location --request POST 'https://api-singapore.klingai.com/v1/videos/image2video' \ +--header 'Authorization: Bearer ' \ +--header 'Content-Type: application/json' \ +--data-raw '{ + "model_name": "kling-v2-6", + "image": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-2.png", + "image_tail": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png", + "prompt": "Camera zooms out, the girl smiles", + "sound": "off", +}' + "request_id": "string", // Request ID, generated by the system + "task_info": { // Task creation parameters + "external_task_id": "string" // Customer-defined task ID + "created_at": 1722769557708, // Task creation time, Unix timestamp, unit ms + "updated_at": 1722769557708 // Task update time, Unix timestamp, unit ms +💡 +Please note that in order to maintain naming consistency, the original model field has been changed to model\_name. Please use this field to specify the model version in the future. +We maintain backward compatibility. If you continue using the original model field, it will not affect API calls and will be equivalent to the default behavior when model\_name is empty (i.e., calling the V1 model). +Enum values：kling-v1kling-v1-5kling-v1-6kling-v2-masterkling-v2-1kling-v2-1-masterkling-v2-5-turbokling-v2-6kling-v3 +imagestringOptional +Reference Image +- Supports image Base64 encoding or image URL (ensure accessibility) +- Supported image formats: `.jpg / .jpeg / .png` +- File size: ≤10MB, dimensions: min 300px, aspect ratio: 1:2.5 ~ 2.5:1 +- At least one of `image` or `image_tail` must be provided; both cannot be empty +Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. +image\_tailstringOptional +Reference Image - End frame control +- Supports image Base64 encoding or image URL (ensure accessibility) +- Supported image formats: `.jpg / .jpeg / .png` +- File size: ≤10MB, dimensions: min 300px +- At least one of `image` or `image_tail` must be provided; both cannot be empty +- `image_tail`, `dynamic_masks/static_mask`, and `camera_control` are mutually exclusive - only one can be used at a time +Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. +Whether to generate multi-shot video +When true: the prompt parameter is invalid, and the first/end frame generation is not supported. +When false: the shot\_type and multi\_prompt parameters are invalid +shot\_typestringOptional +Storyboard method +Enum values：customizeintelligence +When multi\_shot is true, this parameter is required +promptstringOptional +💡 +The Omni model can achieve various capabilities through Prompt with elements, images, videos, and other content: +- Specify elements/images/videos using <<<>>> format, e.g.: <<>>, <<>>, <<>> +- For detailed capabilities, see: [KLING Omni Model User Guide](https://kling.ai/quickstart/klingai-video-o1-user-guide), [Kling VIDEO 3.0 Omni Model User Guide](https://kling.ai/quickstart/klingai-video-3-omni-model-user-guide) +- When multi\_shot is false or shot\_type is intelligence, this parameter must not be empty. +- Use `<<>>` to specify voice, with the sequence matching the voice\_list parameter order +- A video generation task can reference up to 2 voices; when specifying a voice, the sound parameter must be "on" +- The simpler the syntax structure, the better. Example: `The man<<>> said: "Hello"` +- When voice\_list is not empty and prompt references voice ID, the task will be billed as "with specified voice" +Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. +multi\_promptarrayOptional +Information about each storyboard, such as prompts and duration +Define the shot sequence number, corresponding prompt word, and duration through the index, prompt, and duration parameters, where: +- Supports up to 6 storyboards, with a minimum of 1 storyboard. +- The maximum length of the prompt for each storyboard 512 characters. +- The duration of each storyboard should not exceed the total duration, but should not be less than 1. +- The sum of the durations of all storyboards equals the total duration of the current task. +Load with key:value format as follows: +"multi_prompt":[ +{"index":int,"prompt":"string","duration":"5"}, +{"index":int,"prompt":"string","duration":"5"} +When multi\_shot is true and shot\_type is customize, this parameter is required. +element\_listarrayOptional +Reference Element List, based on element ID from element library +- Supports up to 3 reference elements +The elements are categorized into video customization element (named as Video Character Elements) and image customization elements (named as Multi-Image Elements), each with distinct scopes of application. Please exercise caution in distinguishing between them. See [Kling Element Library User Guide](https://kling.ai/quickstart/klingai-element-library-3-user-guide). +- Load with key:value format as follows: +"element_list":[ + { "element_id": long }, + { "element_id": long } +Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. +element\_idlongRequired +Element ID from element library +voice\_listarrayOptional +List of voices referenced when generating videos +- A video generation task can reference up to 2 voices +- When voice\_list is not empty and prompt references voice ID, the task will be billed as "with specified voice" +- voice\_id is returned through the voice customization API, or use system preset voices. See [Custom Voices API](https://kling.ai/document-api/apiReference/model/customVoices); NOT the voice\_id of Lip-Sync API +- element\_list and voice\_list are mutually exclusive and cannot coexist +Example: +"voice_list":[ + {"voice_id":"voice_id_1"}, + {"voice_id":"voice_id_2"} +The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) +Whether to generate sound when generating video +Enum values：onoff +The support range for different model versions and video modes varies. For details, see [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) +Flexibility in video generation; higher value means lower model flexibility and stronger relevance to user prompt +- Value range: \[0, 1\] +kling-v2.x models do not support this parameter +Enum values：stdpro4k +- `std`: Standard Mode, basic mode, cost-effective. The output video resolution is 720P. +- `pro`: Professional Mode, generates videos use longer duration but higher quality video output. The output video resolution is 1080P. +- `4k`: 4K Mode, generates videos use longer duration but higher quality video output. The output video resolution is 4K. +Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. +static\_maskstringOptional +Static brush mask area (mask image created by user using motion brush) +The "Motion Brush" feature includes Dynamic Brush (dynamic\_masks) and Static Brush (static\_mask) +- Supports image Base64 encoding or image URL (same format requirements as image field) +- Supported image formats: `.jpg / .jpeg / .png` +- Aspect ratio must match the input image (image field), otherwise task will fail +- Resolution of static\_mask and dynamic\_masks.mask must be identical, otherwise task will fail +Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. +dynamic\_masksarrayOptional +Dynamic brush configuration list +- Can configure multiple groups (up to 6), each containing "mask area" and "motion trajectory" sequence +Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. +maskstringRequired +Dynamic brush mask area (mask image created by user using motion brush) +- Supports image Base64 encoding or image URL (same format requirements as image field) +- Aspect ratio must match the input image (image field), otherwise task will fail +- Resolution of static\_mask and dynamic\_masks.mask must be identical, otherwise task will fail +trajectoriesarrayRequired +Motion trajectory coordinate sequence +- For 5s video, trajectory length ≤77, coordinate count range: \[2, 77\] +- Coordinate system uses bottom-left corner of image as origin +Note 1: More coordinate points = more accurate trajectory. 2 points = straight line between them +Note 2: Trajectory direction follows input order. First coordinate is start point, subsequent coordinates are connected sequentially +xintRequired +X coordinate of trajectory point (pixel coordinate with image bottom-left as origin) +yintRequired +Y coordinate of trajectory point (pixel coordinate with image bottom-left as origin) +camera\_controlobjectOptional +Camera movement control protocol (if not specified, model will intelligently match based on input text/images) +Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. +typestringRequired +Predefined camera movement type +Enum values：simpledown\_backforward\_upright\_turn\_forwardleft\_turn\_forward +- simple: Simple camera movement, can choose one of six options in "config" +- down\_back: Camera descends and moves backward ➡️ Pan down and zoom out. config parameter not required +- forward\_up: Camera moves forward and tilts up ➡️ Zoom in and pan up. config parameter not required +- right\_turn\_forward: Rotate right then move forward ➡️ Right rotation advance. config parameter not required +- left\_turn\_forward: Rotate left then move forward ➡️ Left rotation advance. config parameter not required +configobjectOptional +Contains 6 fields to specify camera movement in different directions +- Required when type is "simple"; leave empty for other types +- Choose only one parameter to be non-zero; rest must be 0 +horizontalfloatOptional +Horizontal movement - camera translation along x-axis +- Value range: \[-10, 10\]. Negative = left, Positive = right +verticalfloatOptional +Vertical movement - camera translation along y-axis +- Value range: \[-10, 10\]. Negative = down, Positive = up +panfloatOptional +Horizontal pan - camera rotation around y-axis +- Value range: \[-10, 10\]. Negative = rotate left, Positive = rotate right +tiltfloatOptional +Vertical tilt - camera rotation around x-axis +- Value range: \[-10, 10\]. Negative = tilt down, Positive = tilt up +rollfloatOptional +Roll - camera rotation around z-axis +- Value range: \[-10, 10\]. Negative = counterclockwise, Positive = clockwise +zoomfloatOptional +Zoom - controls camera focal length change, affects field of view +- Value range: \[-10, 10\]. Negative = longer focal length (narrower FOV), Positive = shorter focal length (wider FOV) +Video duration in seconds +Enum values：3456789101112131415 +Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details. +Callback notification URL for task result. If configured, server will notify when task status changes. +- Will not overwrite system-generated task ID, but supports querying task by this ID +- Must be unique within a single user account +## Scenario invocation examples +### Image to video with multi-shot +curl --location 'https://xxx/v1/videos/image2video' \ +--header 'Authorization: Bearer xxx' \ +--header 'Content-Type: application/json' \ +--data '{ + "model_name": "kling-v3", + "image": "xxx", + "prompt": "", + "multi_shot": "true", + "shot_type": "customize", + "multi_prompt": [ + "index": 1, + "prompt": "Two friends talking under a streetlight at night. Warm glow, casual poses, no dialogue.", + "duration": "2" + }, + "index": 2, + "prompt": "A runner sprinting through a forest, leaves flying. Low-angle shot, focus on movement.", + "duration": "3" + }, + "index": 3, + "prompt": "A woman hugging a cat, smiling. Soft sunlight, cozy home setting, emphasize warmth.", + "duration": "3" + }, + "index": 4, + "prompt": "A door creaking open, shadowy hallway. Dark tones, minimal details, eerie mood.", + "duration": "3" + }, + "index": 5, + "prompt": "A man slipping on a banana peel, shocked expression. Exaggerated pose, bright colors.", + "duration": "3" + }, + "index": 6, + "prompt": "A sunset over mountains, small figure walking away. Wide angle, peaceful atmosphere.", + "duration": "1" + "duration": "15", + "sound": "on", +}' +### Image to video with element +curl --location 'https://api-singapore.klingai.com/v1/images/generations' \ +--header 'Authorization: Bearer xxx' \ +--header 'Content-Type: application/json' \ +--data '{ + "model_name": "kling-v3", + "prompt": "Merge all the characters from the images into the <<>> diagram", + "element_list": [ + "element_id": "160" + }, + "element_id": "161" + }, + "element_id": "159" + "image": "xxx", + "resolution": "2k", + "n": "9", + "aspect_ratio": "3:2", +}' +curl --location 'https://xxx/v1/videos/text2video' \ +--header 'Authorization: Bearer xxx' \ +--header 'Content-Type: application/json' \ +--data '{ + "model_name": "kling-v3", + "prompt": "", + "multi_prompt": [ + "index": 1, + "prompt": "Two friends talking under a streetlight at night. Warm glow, casual poses, no dialogue.", + "duration": "2" + }, + "index": 2, + "prompt": "A runner sprinting through a forest, leaves flying. Low-angle shot, focus on movement.", + "duration": "3" + }, + "index": 3, + "prompt": "A woman hugging a cat, smiling. Soft sunlight, cozy home setting, emphasize warmth.", + "duration": "3" + }, + "index": 4, + "prompt": "A door creaking open, shadowy hallway. Dark tones, minimal details, eerie mood.", + "duration": "3" + }, + "index": 5, + "prompt": "A man slipping on a banana peel, shocked expression. Exaggerated pose, bright colors.", + "duration": "3" + }, + "index": 6, + "prompt": "A sunset over mountains, small figure walking away. Wide angle, peaceful atmosphere.", + "duration": "1" + "multi_shot": true, + "shot_type": "customize", + "duration": "15", + "sound": "on", + "aspect_ratio": "9:16", +}' +### Generate video with voice control +curl --location 'https://api-singapore.klingai.com/v1/videos/image2video/' \ +--header 'Authorization: Bearer {Replace your token}' \ +--header 'Content-Type: application/json; charset=utf-8' \ +--data '{ + "model_name": "kling-v2-6", + "image": "Replace the URL of image", + "prompt": "<<>>Ask the people in the picture to say the following words, '\''Welcome everyone'\''", //If a specific dialogue needs to be enclosed in quotation marks + "voice_list": [ + "voice_id": "Replace the ID of voice" + "sound": "on", +}' +GET `/v1/videos/image2video/{id}` + --url https://api-singapore.klingai.com/v1/videos/image2video/{task_id} \ + "request_id": "string", // Request ID, generated by the system, is used to track requests and troubleshoot problems + "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) + "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) + "watermark_url": "string", // Watermarked video download URL, anti-leech format + "duration": "string" // Total video duration, unit: s + "task_info": { // Task creation parameters + "external_task_id": "string" // Customer-defined task ID + "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms +Task ID for image to video +- Request path parameter, fill value directly in request path +- Choose one between task\_id and external\_task\_id for querying +Customized Task ID for image to video +- The external\_task\_id provided when creating the task +- Choose one between task\_id and external\_task\_id for querying +GET `/v1/videos/image2video` + --url 'https://api-singapore.klingai.com/v1/videos/image2video?pageNum=1&pageSize=30' \ + "code": 0, // Error codes; Specific definitions can be found in Error codes + "request_id": "string", // Request ID, generated by the system, to track requests and troubleshoot problems + "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.) + "task_info": { // Task creation parameters + "external_task_id": "string" // Customer-defined task ID + "url": "string", // URL for generating videos (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) + "watermark_url": "string", // Watermarked video download URL, anti-leech format + "duration": "string" // Total video duration, unit: s (seconds) + "updated_at": 1722769557708 // Task update time, Unix timestamp, unit: ms +Data volume per page + +source: "https://kling.ai/document-api/apiReference/model/videoExtension" +POST `/v1/videos/video-extend` + --url https://api-singapore.klingai.com/v1/videos/video-extend \ + "prompt": "A puppy appears", + "video_id": "743211632612511839", + "task_info":{ // Task creation parameters +- Note 1: Video extension refers to extending the duration of text-to-video/image-to-video results. Each extension can add 4 to 5 seconds, and the model and mode used cannot be selected; they must be the same as the source video. +- Note 2: Videos that have been extended can be extended again, but the total video duration cannot exceed 3 minutes. +video\_idstringRequired +Video ID +- Supports video IDs generated by the text-to-video, the image-to-video and the video extension interface (it cannot exceed 3 minutes). +- Only videos generated by V1.0, V1.5, and V1.6 models are supported. +> Please note that based on the current cleanup policy, videos will be cleared 30 days after generation, and extension will not be possible. +Text Prompt +Cannot exceed 2500 characters +Cannot exceed 2500 characters +Prompt reference strength. The higher the value, the stronger the reference to the prompt. +Value range: \[0, 1\] +The callback notification address for the task results. If configured, the server will actively notify when the task status changes. +GET `/v1/videos/video-extend/{id}` + --url https://api-singapore.klingai.com/v1/videos/video-extend/{task_id} \ + "task_info": { + "parent_video": { //Parameters information when the task is created + "id": "string", //Video ID before the extension；globally unique + "url": "string", //URL for generating images(To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) + "duration": "string" //Original video duration, unit: s (seconds) + "id": "string", // Generated video ID; globally unique, will be cleared after 30 days +Task ID for Video Generation. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying. +Customized Task ID for Video Generation. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying. +GET `/v1/videos/video-extend` + --url 'https://api-singapore.klingai.com/v1/videos/video-extend?pageNum=1&pageSize=30' \ + "task_info": { + "parent_video": { //Parameters information when the task is created + "id": "string", //Video ID before the extension；globally unique + "url": "string", //URL for generating images(To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) + "duration": "string" //Original video duration, unit: s (seconds) + "id": "string", // Generated video ID; globally unique, will be cleared after 30 days +Value range: \[1, 1000\] +Value range: \[1, 500\] + +source: "https://kling.ai/document-api/apiReference/model/textToVideo" +POST `/v1/videos/text2video` + --url https://api-singapore.klingai.com/v1/videos/text2video \ + "prompt": "A cute little rabbit wearing glasses, sitting at a table, reading a newspaper, with a cup of cappuccino on the table", + "aspect_ratio": "1:1", +Please note that in order to maintain naming consistency, the original model field has been changed to model\_name, so in the future, please use this field to specify the version of the model that needs to be called. +At the same time, we keep the behavior forward-compatible. If you continue to use the original model field, it will not have any impact on the interface call, there will not be any exception, which is equivalent to the default behavior when model\_name is empty (i.e., call the V1 model). +Authentication information, refer to API authorization +Enum values：kling-v1kling-v1-6kling-v2-masterkling-v2-1-masterkling-v2-5-turbokling-v2-6kling-v3 +- Use <<>> to specify voice, same sequence as voice\_list. Up to 2 voices; when specifying voice, sound must be on. Simpler grammar is better. For example: The man <<>> said, "Hello.". +- When voice\_list is not empty and prompt references voice ID, task is billed as "with voice generation". +Each storyboard cue can include both positive and negative descriptions +Is sound generated simultaneously when generating videos +The degree of freedom for generating video; the larger the value, the smaller the degree of freedom of the model +Terms of controlling camera movement (if not specified, the model will intelligently match based on the input text/images) +typestringOptional +Predefined camera movements type +- simple: Simple camera movement, you can choose one of six options in "config" +- down\_back: Camera descends and moves backward ➡️ Pan down and zoom out. The config parameter must be set to "None" under this type. +- forward\_up: Camera moves forward and tilts up ➡️ Zoom in and pan up. The config parameter must be set to "None" under this type. +- right\_turn\_forward: Rotate right then move forward ➡️ Rotate right and advance. The config parameter must be set to "None" under this type. +- left\_turn\_forward: Rotate left then move forward ➡️ Rotate left and advance. The config parameter must be set to "None" under this type. +Contains 6 fields, used to specify the camera's movement or change in different directions +- Required when type is simple, not required for other types +- Choose 1 of the following 6 parameters, only one can be non-zero, others must be 0 +Horizontal, controls the camera's movement along the horizontal axis (translation along the x-axis) +- Value range: \[-10, 10\] +- Negative value indicates a translation to the left, positive value indicates a translation to the right +Vertical, controls the camera's movement along the vertical axis (translation along the y-axis) +- Value range: \[-10, 10\] +- Negative value indicates a downward translation, positive value indicates an upward translation +Pan, controls the camera's rotation in the horizontal plane (rotation around the y-axis) +- Value range: \[-10, 10\] +- Negative value indicates rotation to the left around y-axis, positive value indicates rotation to the right around y-axis +Tilt, controls the camera's rotation in the vertical plane (rotation around the x-axis) +- Value range: \[-10, 10\] +- Negative value indicates rotation down around x-axis, positive value indicates rotation up around x-axis +Roll, controls the camera's roll (rotation around the z-axis) +- Value range: \[-10, 10\] +- Negative value indicates counterclockwise rotation around z-axis, positive value indicates clockwise rotation around z-axis +Zoom, controls the camera's focal length change, affecting the distance of the field of view +- Value range: \[-10, 10\] +- Negative value indicates longer focal length, smaller field of view; positive value indicates shorter focal length, larger field of view +Callback notification URL for this task result. If configured, the server will actively notify when the task status changes +- Users can provide a customized task ID, which will not overwrite the system-generated task ID but can be used for task queries +## More Scene Invocation Examples +### Text To Video with Multiple Shot +GET `/v1/videos/text2video/{id}` + --url https://api-singapore.klingai.com/v1/videos/text2video/{task_id} \ + "duration": "string" // Total video duration, unit: s (seconds) +Task ID for text-to-video. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying. +Customized Task ID for text-to-video. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying. +GET `/v1/videos/text2video` + --url 'https://api-singapore.klingai.com/v1/videos/text2video?pageNum=1&pageSize=30' \ + +source: "https://kling.ai/document-api/apiReference/model/multiElements" +## Initialize Video for Editing +POST `/v1/videos/multi-elements/init-selection` + --url https://api-singapore.klingai.com/v1/videos/multi-elements/init-selection \ + "video_id": "", + "video_url": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/animals-output-5s.mp4" + "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting + "status": 0, // Rejection code, non-zero indicates recognition failure + "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours + "fps": 30.0, // Frame rate of parsed video, required when fetching selection preview video + "original_duration": 1000, // Duration of parsed video, required when creating task + "width": 720, // Width of parsed video, currently unused + "height": 1280, // Height of parsed video, currently unused + "total_frame": 300, // Total frame count of parsed video, required when creating task + "normalized_video": "url" // URL of initialized video +Initialize the original video before using Multi-elements feature. When replacing or removing elements within the existing video, the relevant elements need to be marked in the video beforehand. +The ID of the video generated by the Kling AI +- Only videos generated within the last 30 days are supported +- Only supports videos with a duration of ≥2 seconds and ≤5 seconds, or ≥7 seconds and ≤10 seconds +Get link for uploaded video +- Only.mp4/.mov formats are supported +- Only supports videos with a duration of ≥2 seconds and ≤5 seconds, or ≥7 seconds and ≤10 seconds +- Video resolution must be between 720px and 2160px (inclusive) in both width and height +- Only supports videos with frame rates of 24, 30, or 60 fps +## Add Video Selection Area +POST `/v1/videos/multi-elements/add-selection` + --url https://api-singapore.klingai.com/v1/videos/multi-elements/add-selection \ + "session_id": "847570360458960960", + "frame_index": 0, + "points": [ + "x": 0.7738498789346246, + "y": 0.297142857142857 + "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting + "status": 0, // Rejection code, non-zero indicates recognition failure + "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours + "res": { + "frame_index": 0, + "rle_mask_list": [{ + "object_id": 0, + "rle_mask": { + "size": [720, 1280], + "counts": "string" + "png_mask": { + "size": [720, 1280], + "base64": "string" + }] +Session ID, generated during the video initialization task and remains unchanged during editing operations +frame\_indexintRequired +Frame Number +- A maximum of 10 frames can be marked. That is, up to 10 frames can be used to define selection areas in the video +- Only supports marking 1 frame at a time +pointsarrayRequired +Click Coordinates, represented by x and y +- Value range: \[0, 1\], expressed as percentages; \[0, 1\] represents the top-left corner of the frame +- Multiple points can be marked at once; up to 10 points can be marked on a single frame +xfloatRequired +X coordinate \[0-1\] +yfloatRequired +Y coordinate \[0-1\] +### Sample Code +#### Decoding Image Segmentation Result +```typescript +export type RLEObject = { + size: [h: number, w: number] + counts: string +type RLE = { + h: number + w: number + m: number + binaries: number[] +export function decode(rleObj: RLEObject) { + const [h, w] = rleObj.size + const R: RLE = { h, w, m: 0, binaries: [0] } + rleFrString(R, rleObj.counts) + const unitArray = new Uint8Array(h * w) + rleDecode(R, unitArray) + return unitArray +function rleDecode(R: RLE, M: Uint8Array) { + let j + let k + let p = 0 + let v = false + for (j = 0; j < R.m; j++) { + for (k = 0; k < R.binaries[j]; k++) { + const x = Math.floor(p / R.h) + const y = p % R.h + M[y * R.w + x] = v === false ? 0 : 1 // Note: y * width + x indicates row-major (horizontal) layout. + p++ + v = !v +function rleFrString(R: RLE, s: string) { + let m = 0 + let p = 0 + let k + let x + let more + const binaries = [] + while (s[p]) { + x = 0 + k = 0 + more = 1 + while (more) { + const c = s.charCodeAt(p) - 48 + x |= (c & 0x1f) << (5 * k) + more = c & 0x20 + p++ + k++ + if (!more && c & 0x10) { + x |= -1 << (5 * k) + if (m > 2) { + x += binaries[m - 2] + binaries[m++] = x + R.m = m + R.binaries = binaries +#### Rendering the Segmentation Mask Layer +```typescript +// height refers to the video height and width refers to the video width +function drawMask(rleMask: string, height: number, width: number) { + if (!canvasRef.value) return + const ctx = canvasRef.value.getContext('2d') + if (!ctx) return + const decodeData = decode({ counts: rleMask, size: [height, width] }) + const imageData = ctx.createImageData(width, height) + for (let y = 0; y < height; y++) { + for (let x = 0; x < width; x++) { + const index = y * width + x + if (decodeData[index]) { + const imageIndex = index * 4 + // Set pixel color: red, green, blue, alpha + imageData.data[imageIndex] = 116 // red + imageData.data[imageIndex + 1] = 255 // green + imageData.data[imageIndex + 2] = 82 // blue + imageData.data[imageIndex + 3] = 163 // alpha + ctx.putImageData(imageData, 0, 0) +## Delete Video Selection Area +POST `/v1/videos/multi-elements/delete-selection` + --url https://api-singapore.klingai.com/v1/videos/multi-elements/delete-selection \ + "session_id": "847570360458960960", + "frame_index": 0, + "points": [ + "x": 0.7738498789346246, + "y": 0.297142857142857 + "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting + "status": 0, // Rejection code, non-zero indicates recognition failure + "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours + "res": { + "frame_index": 0, + "rle_mask_list": [{ + "object_id": 0, + "rle_mask": { + "size": [720, 1280], + "counts": "string" + "png_mask": { + "size": [720, 1280], + "base64": "string" + }] +Session ID, generated during the video initialization task and remains unchanged during editing operations +frame\_indexintRequired +Frame Number +pointsarrayRequired +Click Coordinates to delete, represented by x and y +- Value range: \[0, 1\], expressed as percentages; \[0, 1\] represents the top-left corner of the frame +- Multiple points can be provided at once +- Coordinates must exactly match those used when adding the video selection area +xfloatRequired +X coordinate \[0-1\] +yfloatRequired +Y coordinate \[0-1\] +## Clear Video Selection +POST `/v1/videos/multi-elements/clear-selection` + --url https://api-singapore.klingai.com/v1/videos/multi-elements/clear-selection \ + "session_id": "847570360458960960" + "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting + "status": 0, // Rejection code, non-zero indicates recognition failure + "session_id": "id" // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours +Session ID, generated during the video initialization task and remains unchanged during editing operations +## Preview Video with Selected Areas +POST `/v1/videos/multi-elements/preview-selection` + --url https://api-singapore.klingai.com/v1/videos/multi-elements/preview-selection \ + "session_id": "847570360458960960" + "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting + "status": 0, // Rejection code, non-zero indicates recognition failure + "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours + "res": { + "video": "url", // Video with mask + "video_cover": "url", // Cover image of video with mask + "tracking_output": "url" // Mask result for each frame in image segmentation results +Session ID, generated during the video initialization task and remains unchanged during editing operations +POST `/v1/videos/multi-elements` + --url https://api-singapore.klingai.com/v1/videos/multi-elements \ + "session_id": "847570360458960960", + "edit_mode": "removal", + "image_list": [], + "prompt": "Delete the chick from <<>>", + "mode": "std", + "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting + "external_task_id": "string" // User-defined task ID +Session ID, generated during the video initialization task and remains unchanged during editing operations +edit\_modestringRequired +Operation Type +Enum values：additionswapremoval +- addition: Add an element +- swap: Replace an element +- removal: Remove an element +image\_listarrayOptional +Cropped Reference Images +- For adding video elements: This parameter is required; upload 1–2 images +- For editing (swapping) video elements: This parameter is required; upload 1 image only +- For deleting video elements: This parameter is not required +- Use key:value format as follows: +- The API does not perform cropping, please upload images with subjects already cropped +Positive Prompt +- Use the format <<>> to explicitly refer to a specific video or image, such as <<>> or <<>> +- To ensure optimal results, the prompt must include references to the video and image(s) required for the editing +- Must not exceed 2,500 characters +**Recommended Prompt Templates:** +**Adding Elements:** +- EN: Using the context of <<>>, seamlessly add \[x\] from <<>> +- ZH: 基于<<>>中的原始内容，以自然生动的方式，将<<>>中的【】，融入<<>>的【】 +**Replacing Elements:** +- EN: swap \[x\] from <<>> for \[x\] from <<>> +- ZH: 使用<<>>中的【】，替换<<>>中的【】 +**Removing Elements:** +- EN: Delete \[x\] from <<>> +- ZH: 删除<<>>中的【】 +Note: \[x\] or 【】 are placeholders where you should fill in specific content. +Negative Prompt +- Must not exceed 2,500 characters +Video Generation Mode +- std: Standard mode, basic rendering, cost-effective +- pro: Professional mode, high-quality, enhanced rendering, better video output quality +Video Duration (in seconds) +- Only 5-second and 10-second videos are supported +- To generate a 5-second video, the input video must be ≥2 seconds and ≤5 seconds +- To generate a 10-second video, the input video must be ≥7 seconds and ≤10 seconds +Callback URL for Task Result Notification. If configured, the server will actively send notifications when the task status changes +- For the message schema, refer to the [Callback Protocol](https://kling.ai/document-api/apiReference/callbackProtocol) +- A user-defined task ID; it will not overwrite the system-generated task ID, but can be used to query the task +- Please ensure uniqueness of the task ID within a single user account +GET `/v1/videos/multi-elements/{id}` + --url https://api-singapore.klingai.com/v1/videos/multi-elements/{task_id} \ + "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting + "task_status_msg": "string", // Task status message, displays failure reason when task fails (e.g., triggered platform content moderation) + "external_task_id": "string" // User-defined task ID + "id": "string", // Generated video ID, globally unique + "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours + "url": "string", // URL of generated video (Note: For security purposes, generated images/videos will be deleted after 30 days, please save them promptly) +Task ID for Multi-Elements video editing +Custom Task ID for Multi-Elements video editing +GET `/v1/videos/multi-elements` + --url 'https://api-singapore.klingai.com/v1/videos/multi-elements?pageNum=1&pageSize=30' \ + "request_id": "string", // Request ID, generated by the system, used for tracking requests and troubleshooting + "task_status_msg": "string", // Task status message, displays failure reason when task fails (e.g., triggered platform content moderation) + "external_task_id": "string" // User-defined task ID + "id": "string", // Generated video ID, globally unique + "session_id": "id", // Session ID, generated during video initialization task, remains unchanged during editing operations, valid for 24 hours + "url": "string", // URL of generated video (Note: For security purposes, generated images/videos will be deleted after 30 days, please save them promptly) + "duration": "string" // Total video duration, unit: s + +source: "https://kling.ai/document-api/apiReference/model/motionControl" +POST `/v1/videos/motion-control` + --url https://api-singapore.klingai.com/v1/videos/motion-control \ + --header 'Content-Type: application/json; charset=utf-8' \ + --data-raw '{ + "image_url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-3.ng.png", + "prompt": "The girl is wearing a loose gray T-shirt and denim shorts", + "video_url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dance.mp4", + "keep_original_sound": "yes", + "character_orientation": "image", + "external_task_id": "xxx" + "external_task_id": "string" //Customer-defined task ID +Enum values：kling-v2-6kling-v3 +Text prompt, can include positive and negative descriptions +- Can add elements to the scene, achieve camera movement effects, etc. See [Kling "Motion Control" User Guide](https://kling.ai/quickstart/motion-control-user-guide) +image\_urlstringRequired +Reference image. Characters, background and other elements in generated video will follow this reference. +- Video content requirements: + - Character proportions should match the reference motion as much as possible; avoid driving half-body characters with full-body motions + - Character should show clear upper body or full body including limbs and head, avoid occlusion + - Avoid extreme orientations (upside down, lying flat, etc.). Character should occupy sufficient screen area + - Supports realistic/stylized characters (including humans/humanoid animals/some pure animals/some humanoid body proportion characters) +- File size: ≤10MB, dimensions: 300px ~ 65536px, aspect ratio: 1:2.5 ~ 2.5:1 +video\_urlstringRequired +URL of reference video. Character actions in generated video will follow this reference. +- Video content requirements: + - Character should show clear upper body or full body including all limbs and head, avoid occlusion + - Recommend uploading single-person action video; for 2+ people, actions will be taken from the character with largest screen proportion + - Recommend using real person actions; some stylized characters/humanoid body proportions may work + - Video should be single continuous shot with character always visible, avoid cuts or camera movements (will be truncated otherwise) + - Avoid overly fast actions; relatively stable actions produce better results +- Supported formats:.mp4 /.mov, file size: ≤100MB, dimensions: 340px ~ 3850px. Validation failures will return error codes. +- Duration limits: minimum 3 seconds, maximum depends on character\_orientation: + - When character\_orientation is "video": maximum 30 seconds + - When character\_orientation is "image": maximum 10 seconds +- The duration range of the uploaded motion reference is from 3 to 30 seconds, in which the generated video length will align with the duration of the uploaded video. If motions are complex or fast-paced, there is a chance that the output may be shorter than the uploaded video duration, as the model can only extract the valid action duration for generation. The minimum extractable continuous action duration is 3 seconds. Please note that in such cases, the consumed credits cannot be refunded. It is recommended to adjust the complexity and speed of the actions accordingly. +- System will validate video content and return error codes if issues are found +Reference Element List based on element ID configuration + { "element_id": 829836802793406551 } +- When referencing the element, the generated video can only temporarily refer to the orientation of the person in the video. +- Currently, only one element can be introduced. +Whether to keep the original sound of the video +Enum values：yesno +character\_orientationstringRequired +Character orientation in generated video, can match image or video +Enum values：imagevideo +- image: Match character orientation in the image; reference video duration must not exceed 10 seconds +- video: Match character orientation in the video; reference video duration must not exceed 30 seconds +- When referencing the element, the generated video can only temporarily refer to the orientation of the person in the video. +modestringRequired +- std: Standard Mode - basic mode, cost-effective +- pro: Professional Mode (High Quality) - high performance mode, better video quality +GET `/v1/videos/motion-control/{id}` + --url https://api-singapore.klingai.com/v1/videos/motion-control/{task_id} \ + "external_task_id": "string" //Customer-defined task ID + "url": "string", // URL for generating videos, anti-leech format (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) + }, +Task ID for Motion Control. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying. +Customized Task ID for Motion Control. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying. +GET `/v1/videos/motion-control` + --url 'https://api-singapore.klingai.com/v1/videos/motion-control?pageNum=1&pageSize=30' \ + "external_task_id": "string" //Customer-defined task ID + "url": "string", // URL for generating videos, anti-leech format (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.) diff --git a/raw/_processed/Modifying system prompts 1.md b/raw/_processed/Modifying system prompts 1.md deleted file mode 100644 index 7c92fc3..0000000 --- a/raw/_processed/Modifying system prompts 1.md +++ /dev/null @@ -1,356 +0,0 @@ ---- -title: "Modifying system prompts" -source: "https://code.claude.com/docs/en/agent-sdk/modifying-system-prompts" -author: -published: -created: 2026-04-17 -description: "Learn how to customize Claude's behavior by modifying system prompts using three approaches - output styles, systemPrompt with append, and custom system prompts." -tags: - - "clippings" ---- -System prompts define Claude’s behavior, capabilities, and response style. The Claude Agent SDK provides three ways to customize system prompts: using output styles (persistent, file-based configurations), appending to Claude Code’s prompt, or using a fully custom prompt. - -## Understanding system prompts - -A system prompt is the initial instruction set that shapes how Claude behaves throughout a conversation. - -**Default behavior:** The Agent SDK uses a **minimal system prompt** by default. It contains only essential tool instructions but omits Claude Code’s coding guidelines, response style, and project context. To include the full Claude Code system prompt, specify `systemPrompt: { type: "preset", preset: "claude_code" }` in TypeScript or `system_prompt={"type": "preset", "preset": "claude_code"}` in Python. - -Claude Code’s system prompt includes: - -- Tool usage instructions and available tools -- Code style and formatting guidelines -- Response tone and verbosity settings -- Security and safety instructions -- Context about the current working directory and environment - -## Methods of modification - -### Method 1: CLAUDE.md files (project-level instructions) - -CLAUDE.md files provide project-specific context and instructions that are automatically read by the Agent SDK when it runs in a directory. They serve as persistent “memory” for your project. - -#### How CLAUDE.md works with the SDK - -**Location and discovery:** - -- **Project-level:** `CLAUDE.md` or `.claude/CLAUDE.md` in your working directory -- **User-level:** `~/.claude/CLAUDE.md` for global instructions across all projects - -CLAUDE.md files are read when the corresponding setting source is enabled: `'project'` for project-level CLAUDE.md and `'user'` for `~/.claude/CLAUDE.md`. With default `query()` options both sources are enabled, so CLAUDE.md loads automatically. If you set `settingSources` (TypeScript) or `setting_sources` (Python) explicitly, include the sources you need. CLAUDE.md loading is controlled by setting sources, not by the `claude_code` preset. - -**Content format:** CLAUDE.md files use plain markdown and can contain: - -- Coding guidelines and standards -- Project-specific context -- Common commands or workflows -- API conventions -- Testing requirements - -#### Example CLAUDE.md - -```markdown -# Project Guidelines - -## Code Style - -- Use TypeScript strict mode -- Prefer functional components in React -- Always include JSDoc comments for public APIs - -## Testing - -- Run \`npm test\` before committing -- Maintain >80% code coverage -- Use jest for unit tests, playwright for E2E - -## Commands - -- Build: \`npm run build\` -- Dev server: \`npm run dev\` -- Type check: \`npm run typecheck\` -``` - -#### Using CLAUDE.md with the SDK - -```typescript -import { query } from "@anthropic-ai/claude-agent-sdk"; - -const messages = []; - -for await (const message of query({ - prompt: "Add a new React component for user profiles", - options: { - systemPrompt: { - type: "preset", - preset: "claude_code" // Use Claude Code's system prompt - }, - settingSources: ["project"] // Loads CLAUDE.md from project - } -})) { - messages.push(message); -} - -// Now Claude has access to your project guidelines from CLAUDE.md -``` - -#### When to use CLAUDE.md - -**Best for:** - -- **Team-shared context** - Guidelines everyone should follow -- **Project conventions** - Coding standards, file structure, naming patterns -- **Common commands** - Build, test, deploy commands specific to your project -- **Long-term memory** - Context that should persist across all sessions -- **Version-controlled instructions** - Commit to git so the team stays in sync - -**Key characteristics:** - -- ✅ Persistent across all sessions in a project -- ✅ Shared with team via git -- ✅ Automatic discovery (no code changes needed) -- ⚠️ Not loaded if you pass `settingSources: []` - -### Method 2: Output styles (persistent configurations) - -Output styles are saved configurations that modify Claude’s system prompt. They’re stored as markdown files and can be reused across sessions and projects. - -#### Creating an output style - -```typescript -import { writeFile, mkdir } from "fs/promises"; -import { join } from "path"; -import { homedir } from "os"; - -async function createOutputStyle(name: string, description: string, prompt: string) { - // User-level: ~/.claude/output-styles - // Project-level: .claude/output-styles - const outputStylesDir = join(homedir(), ".claude", "output-styles"); - - await mkdir(outputStylesDir, { recursive: true }); - - const content = \`--- -name: ${name} -description: ${description} ---- - -${prompt}\`; - - const filePath = join(outputStylesDir, \`${name.toLowerCase().replace(/\s+/g, "-")}.md\`); - await writeFile(filePath, content, "utf-8"); -} - -// Example: Create a code review specialist -await createOutputStyle( - "Code Reviewer", - "Thorough code review assistant", - \`You are an expert code reviewer. - -For every code submission: -1. Check for bugs and security issues -2. Evaluate performance -3. Suggest improvements -4. Rate code quality (1-10)\` -); -``` - -#### Using output styles - -Once created, activate output styles via: - -- **CLI**: `/output-style [style-name]` -- **Settings**: `.claude/settings.local.json` -- **Create new**: `/output-style:new [description]` - -**Note for SDK users:** Output styles are loaded when you include `settingSources: ['user']` or `settingSources: ['project']` (TypeScript) / `setting_sources=["user"]` or `setting_sources=["project"]` (Python) in your options. - -### Method 3: Using systemPrompt with append - -You can use the Claude Code preset with an `append` property to add your custom instructions while preserving all built-in functionality. - -```typescript -import { query } from "@anthropic-ai/claude-agent-sdk"; - -const messages = []; - -for await (const message of query({ - prompt: "Help me write a Python function to calculate fibonacci numbers", - options: { - systemPrompt: { - type: "preset", - preset: "claude_code", - append: "Always include detailed docstrings and type hints in Python code." - } - } -})) { - messages.push(message); - if (message.type === "assistant") { - console.log(message.message.content); - } -} -``` - -#### Improve prompt caching across users and machines - -By default, two sessions that use the same `claude_code` preset and `append` text still cannot share a prompt cache entry if they run from different working directories. This is because the preset embeds per-session context in the system prompt ahead of your `append` text: the working directory, platform and OS version, current date, git status, and auto-memory paths. Any difference in that context produces a different system prompt and a cache miss. - -To make the system prompt identical across sessions, set `excludeDynamicSections: true` in TypeScript or `"exclude_dynamic_sections": True` in Python. The per-session context moves into the first user message, leaving only the static preset and your `append` text in the system prompt so identical configurations share a cache entry across users and machines. - -`excludeDynamicSections` requires `@anthropic-ai/claude-agent-sdk` v0.2.98 or later, or `claude-agent-sdk` v0.1.58 or later for Python. It applies only to the preset object form and has no effect when `systemPrompt` is a string. - -The following example pairs a shared `append` block with `excludeDynamicSections` so a fleet of agents running from different directories can reuse the same cached system prompt: - -```typescript -import { query } from "@anthropic-ai/claude-agent-sdk"; - -for await (const message of query({ - prompt: "Triage the open issues in this repo", - options: { - systemPrompt: { - type: "preset", - preset: "claude_code", - append: "You operate Acme's internal triage workflow. Label issues by component and severity.", - excludeDynamicSections: true - } - } -})) { - // ... -} -``` - -**Tradeoffs:** the working directory, git status, and memory location still reach Claude, but as part of the first user message rather than the system prompt. Instructions in the user message carry marginally less weight than the same text in the system prompt, so Claude may rely on them less strongly when reasoning about the current directory or auto-memory paths. Enable this option when cross-session cache reuse matters more than maximally authoritative environment context. - -For the equivalent flag in non-interactive CLI mode, see [`--exclude-dynamic-system-prompt-sections`](https://code.claude.com/docs/en/cli-reference). - -### Method 4: Custom system prompts - -You can provide a custom string as `systemPrompt` to replace the default entirely with your own instructions. - -```typescript -import { query } from "@anthropic-ai/claude-agent-sdk"; - -const customPrompt = \`You are a Python coding specialist. -Follow these guidelines: -- Write clean, well-documented code -- Use type hints for all functions -- Include comprehensive docstrings -- Prefer functional programming patterns when appropriate -- Always explain your code choices\`; - -const messages = []; - -for await (const message of query({ - prompt: "Create a data processing pipeline", - options: { - systemPrompt: customPrompt - } -})) { - messages.push(message); - if (message.type === "assistant") { - console.log(message.message.content); - } -} -``` - -## Comparison of all four approaches - -| Feature | CLAUDE.md | Output Styles | `systemPrompt` with append | Custom `systemPrompt` | -| --- | --- | --- | --- | --- | -| **Persistence** | Per-project file | Saved as files | Session only | Session only | -| **Reusability** | Per-project | Across projects | Code duplication | Code duplication | -| **Management** | On filesystem | CLI + files | In code | In code | -| **Default tools** | Preserved | Preserved | Preserved | Lost (unless included) | -| **Built-in safety** | Maintained | Maintained | Maintained | Must be added | -| **Environment context** | Automatic | Automatic | Automatic | Must be provided | -| **Customization level** | Additions only | Replace default | Additions only | Complete control | -| **Version control** | With project | Yes | With code | With code | -| **Scope** | Project-specific | User or project | Code session | Code session | - -**Note:** “With append” means using `systemPrompt: { type: "preset", preset: "claude_code", append: "..." }` in TypeScript or `system_prompt={"type": "preset", "preset": "claude_code", "append": "..."}` in Python. - -## Use cases and best practices - -### When to use CLAUDE.md - -**Best for:** - -- Project-specific coding standards and conventions -- Documenting project structure and architecture -- Listing common commands (build, test, deploy) -- Team-shared context that should be version controlled -- Instructions that apply to all SDK usage in a project - -**Examples:** - -- “All API endpoints should use async/await patterns” -- “Run `npm run lint:fix` before committing” -- “Database migrations are in the `migrations/` directory” - -CLAUDE.md files load when the `project` setting source is enabled, which it is for default `query()` options. If you set `settingSources` (TypeScript) or `setting_sources` (Python) explicitly, include `'project'` to keep loading project-level CLAUDE.md. - -### When to use output styles - -**Best for:** - -- Persistent behavior changes across sessions -- Team-shared configurations -- Specialized assistants (code reviewer, data scientist, DevOps) -- Complex prompt modifications that need versioning - -**Examples:** - -- Creating a dedicated SQL optimization assistant -- Building a security-focused code reviewer -- Developing a teaching assistant with specific pedagogy - -### When to use systemPrompt with append - -**Best for:** - -- Adding specific coding standards or preferences -- Customizing output formatting -- Adding domain-specific knowledge -- Modifying response verbosity -- Enhancing Claude Code’s default behavior without losing tool instructions - -### When to use custom systemPrompt - -**Best for:** - -- Complete control over Claude’s behavior -- Specialized single-session tasks -- Testing new prompt strategies -- Situations where default tools aren’t needed -- Building specialized agents with unique behavior - -## Combining approaches - -You can combine these methods for maximum flexibility: - -### Example: Output style with session-specific additions - -```typescript -import { query } from "@anthropic-ai/claude-agent-sdk"; - -// Assuming "Code Reviewer" output style is active (via /output-style) -// Add session-specific focus areas -const messages = []; - -for await (const message of query({ - prompt: "Review this authentication module", - options: { - systemPrompt: { - type: "preset", - preset: "claude_code", - append: \` - For this review, prioritize: - - OAuth 2.0 compliance - - Token storage security - - Session management - \` - } - } -})) { - messages.push(message); -} -``` \ No newline at end of file diff --git a/raw/_processed/Speedtest Tracker Homarr documentation 1.md b/raw/_processed/Speedtest Tracker Homarr documentation 1.md deleted file mode 100644 index a3faba5..0000000 --- a/raw/_processed/Speedtest Tracker Homarr documentation 1.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "Speedtest Tracker | Homarr documentation" -source: "https://homarr.dev/docs/widgets/speedtest-tracker/" -author: -published: -created: 2026-04-19 -description: "Displays speed test results from your Speedtest Tracker instance." -tags: - - "clippings" ---- -Version: 1.59.2 - -## Speedtest Tracker - -Speedtest - -Displays speed test results from your Speedtest Tracker instance. - -This widget displays internet speed test results from your [Speedtest Tracker](https://docs.speedtest-tracker.dev/) instance, including the latest result, historical averages, and a live chart of the last 12 hours. - -### Screenshots - -![[216ccb0acf6725fc7f1f649bfca9c2d1_MD5.png]] - -### Supported Integrations - -![[0795c8913e511175e97c3edde2b79fc8_MD5.png]] - -Speedtest TrackerSpeedtest Tracker is a self-hosted internet performance tracking application. - -[Details](https://homarr.dev/docs/integrations/speedtest-tracker) - -### Adding the widget - -You can find how to add the widget on the [Widgets](https://homarr.dev/docs/getting-started/after-the-installation#embed-integration-data-using-widgets) documentation page. - -### Configuration - -| Name | Description | Values | Default value | -| --- | --- | --- | --- | -| Show latest result | Displays the most recent speed test result, including download speed, upload speed, ping, and health status. | yes / no | yes | -| Show averages | Displays average download speed, upload speed, and ping across all recorded tests. | yes / no | yes | -| Show recent results | Displays an area chart of the last 12 hours of speed test results. | yes / no | yes | -| Show ping results | Displays a chart of ping results. Only shown if 'Show recent results' is disabled. | yes / no | no | \ No newline at end of file diff --git a/raw/_processed/Speedtest Tracker Homarr documentation.md b/raw/_processed/Speedtest Tracker Homarr documentation.md index dcb0ece..521b4f0 100644 --- a/raw/_processed/Speedtest Tracker Homarr documentation.md +++ b/raw/_processed/Speedtest Tracker Homarr documentation.md @@ -32,4 +32,24 @@ You can find how to add the integration on the [Integrations Management](https:/ | Name | Description | | --- | --- | -| API Key | API Key from the service for authentication. | \ No newline at end of file +| API Key | API Key from the service for authentication. | +source: "https://homarr.dev/docs/widgets/speedtest-tracker/" +description: "Displays speed test results from your Speedtest Tracker instance." +Version: 1.59.2 +Displays speed test results from your Speedtest Tracker instance. +This widget displays internet speed test results from your [Speedtest Tracker](https://docs.speedtest-tracker.dev/) instance, including the latest result, historical averages, and a live chart of the last 12 hours. +### Screenshots +![[216ccb0acf6725fc7f1f649bfca9c2d1_MD5.png]] +### Supported Integrations +![[0795c8913e511175e97c3edde2b79fc8_MD5.png]] +Speedtest TrackerSpeedtest Tracker is a self-hosted internet performance tracking application. +[Details](https://homarr.dev/docs/integrations/speedtest-tracker) +### Adding the widget +You can find how to add the widget on the [Widgets](https://homarr.dev/docs/getting-started/after-the-installation#embed-integration-data-using-widgets) documentation page. +### Configuration +| Name | Description | Values | Default value | +| --- | --- | --- | --- | +| Show latest result | Displays the most recent speed test result, including download speed, upload speed, ping, and health status. | yes / no | yes | +| Show averages | Displays average download speed, upload speed, and ping across all recorded tests. | yes / no | yes | +| Show recent results | Displays an area chart of the last 12 hours of speed test results. | yes / no | yes | +| Show ping results | Displays a chart of ping results. Only shown if 'Show recent results' is disabled. | yes / no | no | diff --git a/raw/_processed/Tabby - a terminal for a more modern age 1.md b/raw/_processed/Tabby - a terminal for a more modern age 1.md deleted file mode 100644 index 4337c78..0000000 --- a/raw/_processed/Tabby - a terminal for a more modern age 1.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: "Tabby - a terminal for a more modern age" -source: "https://tabby.sh/about/features" -author: -published: -created: 2026-04-17 -description: "Tabby is a free and open source SSH, local and Telnet terminal with everything you'll ever need." -tags: - - "clippings" ---- -[Download](https://github.com/Eugeny/tabby/releases/latest) [Donate](https://ko-fi.com/eugeny) - -## Features - -![[313070fb08f7b2d4a518ca34112cb90b_MD5.png]] - -##### Smart tabs - -Tabs that detect progress and can notify you when a process is done. - -![[5559772b272a40f9cda1aaa70aafb066_MD5.png]] - -##### 24-bit color - -Support for True Color and base16 infrastructure, as well as over 150 community ANSI color schemes. - -![[5301df323543981595e1612b60107872_MD5.png]] - -##### Customizable hotkeys - -Freely customizable single and multi-chord shortcuts. - -![[5543d00b294bfcd3eef5768b87600084_MD5.png]] - -##### SSH and the kitchen sink - -A built-in SSH client with profiles, SFTP, key management, jump hosts, X11 and the rest. - -![[3a150028f594c9a9591ff77f27e7d002_MD5.png]] - -##### Persistent port forwards - -Preconfigure often-used port forwarding setups. - -![[08b2d982c9f0e647af596db7d1bfc776_MD5.png]] - -##### Zmodem transfers - -Send and receive files directly from the prompt in SSH, telnet and serial session. - -![[f2c9b059eb0fced7c75f0f520588d893_MD5.png]] - -##### Quake mode - -Dock on the side of the screen? Check. Spawn with a key? Sure. Tabs on bottom? No problem. - -![[7256506a2324a89f259d4e6df789cdd2_MD5.png]] - -##### Split tabs - -Freely rearrangeable split panes which you can also save as a profile. - -![[fdedeb5338913d8714b35aecf914cb65_MD5.png]] - -##### Profile manager - -Save all your configured options into hotkey-assignable profiles. - -![[71bd1f3629e03a9404272cdb574c779e_MD5.png]] - -##### Delicate fontwork - -Ligature support, Powerline and Nerd Fonts, emoji, pixel-perfect boxes. - -![[b62db995b71fd47626b6c5820cb91c47_MD5.png]] - -##### Persistent history and tabs - -Tabby remembers your open tabs, and when you accidentally close them, restores the complete terminal state. - -![[4e2bcd986d8ae9d0aa0e0743e19938a9_MD5.png]] - -##### Careful pasting - -Multi-line paste warnings and bracketed paste support prevent accidentaly executing stuff when pasting multiple lines. \ No newline at end of file diff --git a/raw/_processed/Tabby - a terminal for a more modern age.md b/raw/_processed/Tabby - a terminal for a more modern age.md index 031ce17..290ccdb 100644 --- a/raw/_processed/Tabby - a terminal for a more modern age.md +++ b/raw/_processed/Tabby - a terminal for a more modern age.md @@ -84,4 +84,43 @@ Here's a demo 👇 - Shell **profiles** - Simultaneous **multi-pane input** - Optional PuTTY style **right-click paste** and **copy on select** -- macOS vibrancy and Win 10 fluent background support \ No newline at end of file +- macOS vibrancy and Win 10 fluent background support +source: "https://tabby.sh/about/features" +[Download](https://github.com/Eugeny/tabby/releases/latest) [Donate](https://ko-fi.com/eugeny) +## Features +![[313070fb08f7b2d4a518ca34112cb90b_MD5.png]] +##### Smart tabs +Tabs that detect progress and can notify you when a process is done. +![[5559772b272a40f9cda1aaa70aafb066_MD5.png]] +##### 24-bit color +Support for True Color and base16 infrastructure, as well as over 150 community ANSI color schemes. +![[5301df323543981595e1612b60107872_MD5.png]] +##### Customizable hotkeys +Freely customizable single and multi-chord shortcuts. +![[5543d00b294bfcd3eef5768b87600084_MD5.png]] +##### SSH and the kitchen sink +A built-in SSH client with profiles, SFTP, key management, jump hosts, X11 and the rest. +![[3a150028f594c9a9591ff77f27e7d002_MD5.png]] +##### Persistent port forwards +Preconfigure often-used port forwarding setups. +![[08b2d982c9f0e647af596db7d1bfc776_MD5.png]] +##### Zmodem transfers +Send and receive files directly from the prompt in SSH, telnet and serial session. +![[f2c9b059eb0fced7c75f0f520588d893_MD5.png]] +##### Quake mode +Dock on the side of the screen? Check. Spawn with a key? Sure. Tabs on bottom? No problem. +![[7256506a2324a89f259d4e6df789cdd2_MD5.png]] +##### Split tabs +Freely rearrangeable split panes which you can also save as a profile. +![[fdedeb5338913d8714b35aecf914cb65_MD5.png]] +##### Profile manager +Save all your configured options into hotkey-assignable profiles. +![[71bd1f3629e03a9404272cdb574c779e_MD5.png]] +##### Delicate fontwork +Ligature support, Powerline and Nerd Fonts, emoji, pixel-perfect boxes. +![[b62db995b71fd47626b6c5820cb91c47_MD5.png]] +##### Persistent history and tabs +Tabby remembers your open tabs, and when you accidentally close them, restores the complete terminal state. +![[4e2bcd986d8ae9d0aa0e0743e19938a9_MD5.png]] +##### Careful pasting +Multi-line paste warnings and bracketed paste support prevent accidentaly executing stuff when pasting multiple lines. diff --git a/wiki/_master-index.md b/wiki/_master-index.md index f40efbb..40e36c1 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -23,7 +23,7 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/tech-patterns/_index\|tech-patterns/]] | Recurring tech stacks: FastAPI, React/Vite, Next.js, Azure AD, AI, Box, One2Edit, Redis/Celery, cost-tracker | 23 | | [[wiki/architecture/_index\|architecture/]] | Cross-cutting architectural patterns: Docker Compose, multi-agent AI, GCP timeout, RAG, hotfolder, optical-dev deploy, cost-tracker, new-project checklist, troubleshooting playbooks, ADR log, Cloud Run Jobs | 11 | | [[wiki/client-knowledge/_index\|client-knowledge/]] | Per-client notes for Ford, H&M, L'Oréal, Barclays, Ferrero, 3M, BAIC | 7 | -| [[wiki/concepts/_index\|concepts/]] | Atomic knowledge extracted from Claude Code sessions | 108 | +| [[wiki/concepts/_index\|concepts/]] | Atomic knowledge extracted from Claude Code sessions | 109 | | [[wiki/connections/_index\|connections/]] | Cross-cutting insights linking 2+ concepts: FastAPI+Azure AD+Docker trinity, AI→cost-tracker, Apache+Vite basePath, GCP→REST polling, Box+hotfolder, Docker DNS+AdGuard, Celery prefork×faster_whisper memory stacking | 10 | | [[wiki/qa/_index\|qa/]] | Filed answers to queries (saved with `--file-back`) | 0 | | [[wiki/homelab/_index\|homelab/]] | Self-hosted infra: Proxmox install, IOMMU/PCI passthrough, hypervisor setup, budget builds, HP Elitedesk G3, Homarr API + Apps + Boards + Certificates + Integrations + Settings + Tasks + AdGuard + Clock + Docker Stats + Docker Integration + Download Client + Firewall + Proxmox Integration + Radarr + Readarr + Sonarr + Bookmarks + Calendar + Icons + App Widget + Weather + GitHub + Nextcloud + qBittorrent + RSS Feed + Speedtest Tracker + System Health Monitoring + System Resources + Services Map + Media Stack | 43 | diff --git a/wiki/client-knowledge/baic.md b/wiki/client-knowledge/baic.md index 5f93739..296d46c 100644 --- a/wiki/client-knowledge/baic.md +++ b/wiki/client-knowledge/baic.md @@ -58,6 +58,16 @@ ssh baic "sudo systemctl status baic_dashboard.service" | SPA index.html must be no-cache | Old hashes cause blank screen after rebuild | [[wiki/concepts/spa-index-html-cache-control]] | | MS SSO IDs are not UUIDs | `ms-4n0T2x-...` format breaks UUID validators | [[wiki/concepts/microsoft-sso-non-uuid-ids]] | +## Features + +| Feature | Detail | Added | +|---------|--------|-------| +| Per-User Report tab | CSV export for Michael (client stakeholder) — replaces manual Python script previously run ad-hoc | 2026-05-06 | + +## Pending + +- [ ] Set up git deploy: deploy key → Bitbucket → clone to `/opt/baic_dashboard` → `update.sh` (eliminates rsync manual step) + ## Related - [[wiki/infrastructure/server-baic]] — server overview (hosts 40+ domains, not just BAIC) diff --git a/wiki/concepts/_index.md b/wiki/concepts/_index.md index a84f090..2488395 100644 --- a/wiki/concepts/_index.md +++ b/wiki/concepts/_index.md @@ -126,5 +126,6 @@ | [[wiki/concepts/microsoft-sso-non-uuid-ids]] | Microsoft SSO app IDs are not UUIDs (`ms-4n0T2x-...`) — UUID validation in routing/DB silently fails for SSO users | daily/2026-05-06.md | 2026-05-06 | | [[wiki/concepts/memory-compiler-lesson-signal]] | Claude Code built-in memory is unused; real pipeline is memory-compiler hooks; `Lesson: — Reason: ` guarantees flush capture; always use skill FQN to avoid ambiguity | daily/2026-05-06.md | 2026-05-06 | +| [[wiki/concepts/pinia-storeftorefs-array-reactivity]] | Pinia storeToRefs loses reactivity on array assignment in Options API stores — must mutate in-place or use $patch | daily/2026-05-06.md | 2026-05-06 | diff --git a/wiki/concepts/pinia-storeftorefs-array-reactivity.md b/wiki/concepts/pinia-storeftorefs-array-reactivity.md new file mode 100644 index 0000000..94d358d --- /dev/null +++ b/wiki/concepts/pinia-storeftorefs-array-reactivity.md @@ -0,0 +1,116 @@ +--- +title: "Pinia storeToRefs — Array Reassignment Breaks Reactivity" +aliases: [pinia-storeftorefs-reactivity, pinia-array-assignment, pinia-stale-ref] +tags: [pinia, vue, javascript, reactivity, frontend, gotcha, debugging] +sources: + - "daily/2026-05-06.md" +created: 2026-05-06 +updated: 2026-05-06 +--- + +# Pinia `storeToRefs` — Array Reassignment Breaks Reactivity + +In Pinia Options API stores, replacing an array via direct assignment (`this.timeline = newArray`) makes the `Ref` returned by `storeToRefs` go stale. The component's destructured ref holds a reference to the old array object — it never sees the new array. The store itself has correct data; the component sees `[]`. + +## Key Takeaways + +- `this.timeline = data` in a Pinia Options API action causes `storeToRefs`-derived refs to be orphaned — `timeline.value` stays empty while `reportsStore.timeline` has 7 items +- The stale ref fires `watchEffect` exactly once (with the initial empty state) and never again — confirming the ref is orphaned, not the store +- Fix: mutate in-place with `this.timeline.splice(0, this.timeline.length, ...data)` OR use `this.$patch({ timeline: data })` +- Audit all Pinia Options API stores for `this.x = newArray` patterns — replace with splice or $patch +- Related: Vue auth race condition — `initAuth()` called in `App.vue onMounted` races with child component `onMounted` fetches; fix: call `initAuth()` synchronously in `main.ts` before `app.mount()` + +## Details + +### The Stale Ref Pattern + +```javascript +// Pinia Options API store — BROKEN +export const useReportsStore = defineStore('reports', { + state: () => ({ + timeline: [], + }), + actions: { + async fetchTimeline(from, to) { + const data = await reportsAPI.getTimeline(from, to); + this.timeline = data; // ← BREAKS storeToRefs reactivity + }, + }, +}); +``` + +```vue + + +``` + +### The Fix + +```javascript +// Option A: Mutate in-place (preferred — no API change) +async fetchTimeline(from, to) { + const data = await reportsAPI.getTimeline(from, to); + this.timeline.splice(0, this.timeline.length, ...data); // mutates, ref stays valid +}, + +// Option B: $patch (explicit, works in both Options and Setup API) +async fetchTimeline(from, to) { + const data = await reportsAPI.getTimeline(from, to); + this.$patch({ timeline: data }); +}, +``` + +### Diagnosis Signals + +When `data.value.length === 0` but `store.data.length > 0` after an `await`: + +1. **`watchEffect` fires once then stops** — stale ref, not reactive to store changes +2. **Identity check** — `storeToRefs` returns a ref to the original array object; assigning a new array breaks the link +3. **Direct store access works** — `{{ reportsStore.timeline }}` in template renders correctly; `{{ timeline }}` does not + +### Auth Initialization Race Condition + +A related Vue bootstrap gotcha: if `initAuth()` (restoring token from `localStorage`) is called in `App.vue`'s `onMounted`, it races with child components that also call `onMounted` and fire API requests. Both `onMounted` hooks run in the same microtask queue — child components may fetch before auth is set. + +```javascript +// ❌ BROKEN — App.vue onMounted races with child component onMounted +// App.vue +onMounted(() => { + authStore.initAuth(); // may run AFTER DashboardView's onMounted +}); + +// DashboardView.vue +onMounted(async () => { + await fetchData(); // fires with token=null if initAuth lost the race +}); +``` + +```javascript +// ✅ CORRECT — main.ts, synchronous before app.mount() +const app = createApp(App); +app.use(pinia); +app.use(router); + +// Initialize auth synchronously BEFORE mount +const authStore = useAuthStore(pinia); +authStore.initAuth(); // reads from localStorage synchronously + +app.mount('#app'); // all components now have token on first render +``` + +## Related Concepts + +- [[wiki/concepts/zustand-async-hydration]] — same class of "state not ready on first render" bug in React/Zustand +- [[wiki/concepts/react-useref-event-handler-state]] — React's async `useState` requiring `useRef` for synchronous access +- [[wiki/concepts/websocket-react-token-guard]] — similar auth-before-connect pattern + +## Sources + +- [[daily/2026-05-06.md]] — cc-dashboard: Dashboard charts empty despite API returning data; `reportsStore.timeline.length === 7` but `timeline.value.length === 0` after await; fixed by replacing `this.timeline = data` with `this.timeline.splice(...)`; auth race condition fixed by moving `initAuth()` to `main.ts` before `app.mount()` diff --git a/wiki/log.md b/wiki/log.md index de68a26..4c35d1d 100644 --- a/wiki/log.md +++ b/wiki/log.md @@ -1,6 +1,11 @@ # Build Log +## [2026-05-06T23:00:00+01:00] compile | Daily Log 2026-05-06 +- Source: daily/2026-05-06.md +- Articles created: [[wiki/concepts/pinia-storeftorefs-array-reactivity]] +- Articles updated: [[wiki/client-knowledge/baic]] (deploy pattern, service name, Per-User Report) + ## [2026-05-06T21:30:00] compile | 2026-05-06.md (pass 2) - Articles created: [[wiki/concepts/memory-compiler-lesson-signal]], [[wiki/tech-patterns/public-share-link-review]] - Articles updated: [[wiki/client-knowledge/baic]] (added Deploy Gotchas section: no .env, rsync warning benign, deploy.sh initial-setup-only, assets accumulation)