tencent-hunyuan-video-integrator

Integrate Tencent Cloud Hunyuan for text-to-video and image-to-video generation. Use this skill when the application needs AI video generation from text descriptions or static images. Triggers on requ

Files2

View on GitHub

SKILL.md

GitHub

Tencent Cloud Hunyuan Video Generation SDK Integration

Scenarios

  • 文生视频（Text-to-Video）：根据文字描述生成视频内容，适用于营销素材、社交媒体短视频、内容创作
  • 图生视频（Image-to-Video）：将静态图片动画化，适用于产品展示、创意内容、图片动效
  • AI 视频内容生产：自动化批量生成视频内容

Not recommended for:

  • 直接在前端调用（需要暴露密钥）
  • 需要实时结果的场景（视频生成为异步任务，通常需要 1-5 分钟）
  • 高并发场景（默认并发数为 1）

Setup

1. Install Dependencies

npm install tencentcloud-sdk-nodejs@^4.0.0

2. Copy SDK Wrapper

Read lib/tencent-hunyuan-video.ts from this skill and copy it to the project, then use it directly.

your-project/
├── src/
│   ├── lib/
│   │   └── tencent-hunyuan-video.ts  ← Copy here
│   └── ...
└── package.json

Configuration

Zero Configuration (Default)

Genie provides default zero-configuration support using vclm.tencent_cloud.auth-proxy.local as the endpoint. No environment variables are required - Genie has integrated authentication in the proxy gateway by default.

Simply use:

import { createClient } from './lib/tencent-hunyuan-video';
const client = createClient();

Custom Configuration (Optional)

Users can optionally configure environment variables. When configured, Genie will use user-provided credentials instead of the default proxy:

# Optional - Only configure if you want to use your own credentials
TENCENTCLOUD_SECRET_ID=your-secret-id-here
TENCENTCLOUD_SECRET_KEY=your-secret-key-here
TENCENTCLOUD_REGION=ap-guangzhou

Obtaining Credentials (if needed):

  1. Visit Tencent Cloud Console - Access Keys
  2. Click "Create Key" to create API credentials
  3. Copy SecretId and SecretKey

Quick Start

Text-to-Video（文生视频）

import { createClient } from './lib/tencent-hunyuan-video';

const client = createClient();

// 提交任务
const job = await client.submitTextToVideoJob('一只猫在草地上奔跑，写实风格');
console.log('任务 ID:', job.jobId);

// 等待完成
const result = await client.waitForJobCompletion(job.jobId, 'text', {
  pollInterval: 5000,   // 每 5 秒查询一次
  timeout: 600000,      // 最多等待 10 分钟
  onProgress: (status) => console.log('当前状态:', status)
});
console.log('视频 URL:', result.resultVideoUrl);

// 下载视频（URL 24 小时内有效）
await client.downloadVideo(result.resultVideoUrl!, './output/video.mp4');

Image-to-Video（图生视频）

// 使用图片 URL
const job = await client.submitImageToVideoJob(
  { url: 'https://example.com/cat.jpg' },
  {
    prompt: '让这只猫动起来',  // 可选描述
    resolution: '720p',
    fps: 24
  }
);

// 使用 base64 图片
const job2 = await client.submitImageToVideoJob(
  { base64: base64ImageData },
  { resolution: '1080p', fps: 30 }
);

const result = await client.waitForJobCompletion(job.jobId, 'image');
console.log('视频 URL:', result.resultVideoUrl);

Convenience Methods（一体化方法）

// 文生视频：提交 + 等待一步完成
const result = await client.generateTextToVideo(
  '一只猫在草地上奔跑',
  { logoAdd: 0 },  // 不添加水印（需平台已申请关闭）
  { onProgress: (status) => console.log('状态:', status) }
);
console.log('视频 URL:', result.resultVideoUrl);

// 图生视频：提交 + 等待一步完成
const result2 = await client.generateImageToVideo(
  { url: 'https://example.com/cat.jpg' },
  { resolution: '720p', fps: 24 }
);
console.log('视频 URL:', result2.resultVideoUrl);

Response Structure

// 提交任务结果
{
  jobId: string;      // 任务 ID，用于后续查询
  requestId: string;  // 请求 ID
}

// 任务状态（文生视频 / 图生视频通用）
{
  status: 'WAIT' | 'RUN' | 'FAIL' | 'DONE';
  errorCode?: string;        // 错误码（FAIL 时有值）
  errorMessage?: string;     // 错误信息（FAIL 时有值）
  resultVideoUrl?: string;   // 视频 URL（DONE 时有值，24 小时内有效）
  requestId: string;
}

API Capabilities

能力 提交接口 查询接口 说明
文生视频 SubmitHunyuanToVideoJob DescribeHunyuanToVideoJob Prompt 必填，仅支持 720p
图生视频 SubmitImageToVideoGeneralJob DescribeImageToVideoGeneralJob 图片必填，支持 480p/720p/1080p，Fps 可选（16/24/30）

Architecture Integration

Service Layer Pattern (Recommended)

// src/services/video.service.ts
import { createClient } from '../lib/tencent-hunyuan-video';

export class VideoService {
  private client = createClient();

  /**
   * 文生视频：根据文字描述生成视频
   */
  async generateFromText(prompt: string): Promise<string> {
    const result = await this.client.generateTextToVideo(prompt, {
      logoAdd: 1,
    });

    if (!result.resultVideoUrl) {
      throw new Error('视频生成成功但未返回 URL');
    }

    return result.resultVideoUrl;
  }

  /**
   * 图生视频：将图片动画化
   */
  async generateFromImage(
    imageUrl: string,
    options?: { prompt?: string; resolution?: '480p' | '720p' | '1080p' }
  ): Promise<string> {
    const result = await this.client.generateImageToVideo(
      { url: imageUrl },
      {
        prompt: options?.prompt,
        resolution: options?.resolution || '720p',
        fps: 30,
      }
    );

    if (!result.resultVideoUrl) {
      throw new Error('视频生成成功但未返回 URL');
    }

    return result.resultVideoUrl;
  }

  /**
   * 提交任务并异步轮询（适合需要展示进度的场景）
   */
  async submitAndPoll(
    type: 'text' | 'image',
    input: string,
    onProgress: (status: string) => void
  ): Promise<string> {
    let jobId: string;

    if (type === 'text') {
      const job = await this.client.submitTextToVideoJob(input);
      jobId = job.jobId;
    } else {
      const job = await this.client.submitImageToVideoJob({ url: input });
      jobId = job.jobId;
    }

    const result = await this.client.waitForJobCompletion(jobId, type, {
      pollInterval: 5000,
      timeout: 600000,
      onProgress,
    });

    return result.resultVideoUrl!;
  }
}

Limitations

限制项 文生视频 图生视频
Prompt 最大长度 200 字符 可选，无强制限制
分辨率 仅 720p 480p / 720p / 1080p
帧率 不支持配置 16 / 24 / 30（默认 30）
并发任务数 1（默认） 1（默认）
视频 URL 有效期 24 小时 24 小时
最大等待时间 10 分钟（默认） 10 分钟（默认）

Security Best Practices

  1. Never commit credentials: Add .env to .gitignore
  2. Use environment variables: Store all sensitive configuration in .env
  3. Video URL expiration: Download videos promptly (URLs valid 24 hours only)
  4. Backend calls only: Never expose credentials to frontend
  5. LogoAdd parameter: Default is 1 (add watermark). Set to 0 only if the platform account has applied to disable the watermark in the Tencent Cloud console.

Troubleshooting

Authentication Errors

  • Verify credentials in .env file if using custom configuration
  • Check if API key is active in the console
  • Ensure no extra spaces in credential values

Job Failures

  • Check if prompt meets requirements (max 200 characters for text-to-video)
  • Verify input image format and size meet requirements
  • Review errorCode and errorMessage for specific failure reason

Network Errors

  • Check firewall/proxy settings
  • Verify service endpoint is accessible

Video Download Failures

  • Confirm video URL has not expired (24-hour validity)
  • Check if local storage path has write permissions

Timeout Issues

  • Increase timeout in waitForJobCompletion options
  • Video generation typically takes 1-5 minutes

Resources

Related in integration

bluebubbles

Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

by clawdbot
7,675

camsnap

Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

by clawdbot
7,675

eightctl

Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

by clawdbot
7,675