tencent cloud

Tencent Effect SDK

製品紹介
製品概要
製品機能
基本概念
製品のメリット
ユースケース
購入ガイド
価格一覧
購入プロセス
支払い遅滞・払い戻しの説明
Demo 体験
無料テスト
License案内
モバイル版Licenseの追加と更新
PC版Licenseの追加と更新
Web版Licenseの追加と更新
よくある質問
SDK ダウンロード
機能説明
SDK ダウンロード
バージョン履歴
SDK統合ガイド
Tencent Effect SDKの独立した統合
アトミック機能統合ガイド
APIドキュメント
iOS
Android
Flutter
機能の実践
SDKパッケージの簡素化
美顔シーン推奨パラメータ
ショート動画(エンタープライズ版)の移行ガイド
サードパーティプッシュによる美顔の接続(Flutter)
コンテンツ作成ツールの活用
Web美顔エフェクト
製品概要
クイックスタート
SDKへのアクセス
APIドキュメント
体験版
よくあるご質問
よくある質問
一般関連
技術系関連
License関連
TE SDK ポリシー
プライバシーポリシー
データ処理とセキュリティ契約

APIドキュメント

PDF
フォーカスモード
フォントサイズ
最終更新日: 2025-06-06 15:53:05
このドキュメントでは、Web Beauty AR SDKのコアパラメータとメソッドについて説明します。
説明:
Web Beauty AR SDKの滑らかなレンダリングを実現するにはブラウザのハードウェアアクセラレーションを有効にする必要があります。そのため、SDKでは業務側が事前に判断するための検出メソッドを提供しており、サポートされていない場合はブロック処理を行います。
import {ArSdk, isWebGLSupported} from 'tencentcloud-webar'
if(isWebGLSupported()) {
const sdk = new ArSdk({
...
})
} else {
// ブロックロジック
}

初期化パラメータ

import { ArSdk } from 'tencentcloud-webar'
// SDKの初期化
const sdk = new ArSdk({
... // 以下のConfig定義を参照
})
SDKの初期化用Configは以下のパラメータをサポートしています:
パラメータ
説明
タイプ
必須かどうか
module
モジュール設定
type SegmentationLevel = 0 | 1 | 2 // 1.0.19以降では切り抜きモデル選択のためのパラメータを渡すことができ、値が高いほど切り抜き効果が良く、リソース使用が多く、fpsが低くなります
type ModuleConfig = {
beautify: boolean // 美顔のオン・オフ、デフォルトでtrue
segmentation: boolean // 背景切り抜きのオン・オフ、デフォルトでfalse
segmentationLevel: SegmentationLevel // 背景切り抜き精度レベル、デフォルトで0
handGesture: boolean // ジェスチャー認識のオン・オフ、デフォルトでfalse、1.0.23以降でサポート
handLandmark: boolean // 手部トラッキングのオン・オフ、デフォルトでfalse、1.0.23以降でサポート、beautifyとの同時使用は推奨しません
}
非必須、デフォルトで{beautify: true, segmentation: false, segmentationLevel: 0,
handLandmark: false}
auth
認証パラメータ
type AuthConfig = {
licenseKey: string // コントロールパネル Web License管理で取得
appId: string // コントロールパネル アカウント情報→基本情報でAPPIDを確認
authFunc:() => Promise<{
signature:string,
timestamp:string
}> // License設定使用を参照
}
必須
input
メディア入力ソース、mediaStream、画像、動画の処理が可能
MediaStream | HTMLImageElement | String | HTMLVideoElement
非必須
camera
内蔵カメラ
type CameraConfig = {
width: number, // 撮影画面の幅
height: number, // 撮影画面の高さ
mirror: boolean, // リバーサルミラー効果のオン・オフ
frameRate: number // 画面キャプチャーのフレームレート
}
非必須
mirror
リバーサルミラーのオン・オフ、入力ストリームのミラーリングをサポート(1.0.19の新機能)
Boolean
非必須
beautify
美顔パラメータ
type BeautifyOptions = {
whiten?: number; // 美白 0~1
dermabrasion?: number; // 美肌 0~1
lift?: number; // 細顔 0~1
shave?: number; // 小顔 0~1
eye?: number; // デカ目 0~1
chin?: number; // 顎 0~1
// 注意:以下のパラメータは1.0.11以降のバージョンでのみ使用可能です
darkCircle?: number; // クマ 0~1
nasolabialFolds?: number; // ほうれい線 0~1
cheekbone?: number; // 頬骨 0~1
head?: number; // 小頭 0~1
eyeBrightness?: number; // キラ目 0~1
lip?: number; // 唇 -1~1
forehead?: number; // 生え際 0~1
nose?: number; // 鼻 -1~1
usm?: number; // シャープネス 0~1
}
非必須
background
背景パラメータ
type BackgroundOptions = {
type: 'image' | 'blur' | 'transparent' | 'video', // 1.0.23以降はvideoタイプの動的背景をサポート
src?: string, // imageまたはvideoタイプで指定される画像アドレス
edgeBlur ?: number, // 1.0.25以降はサポート、値の範囲:0~10、エッジぼかし度を制御、値が小さいほどエッジの切り取りが鋭く、ぼかし度が低くなります。
}
非必須
loading
内蔵loading icon設定
type loadingConfig = {
enable: boolean,
size?: number
lineWidth?: number
strokeColor?: number
}

language
国際化対応(1.0.6以降サポート)、中国語(zh)と英語(en)。
バージョン1.0.26で日本語(jp)をサポート
String: zh | en|jp
非必須、デフォルトでzh
logLevel
コンソールログ出力レベル
'OFF' | 'ERROR' | 'WARN' | 'DEBUG' | 'TRACE' | 'INFO'
非必須、デフォルトでINFO、すべて出力
initReport
ログ報告モジュールを初期化
Boolean
非必須、デフォルトでtrue
worker
ブラウザworkerを無効化、特定シナリオのパフォーマンスを向上
String: auto | disable
非必須、デフォルトでauto、SDKは現在のブラウザ環境に基づいてworkerの使用を決定
proxyServer
イントラネットプロキシモード用
type proxyServeConfig = {
webarProxy: string; // インターフェースプロキシのイントラネットアドレス
staticProxy: string; // リソースプロキシのイントラネットアドレス
}
非必須

コールバックイベント

let effectList = [];
let filterList = [];
// sdkのコールバック使用方法
sdk.on('created', () => {
// createdコールバックでエフェクトとフィルターのリストを取得してページに表示
sdk.getEffectList({
Type: 'Preset',
Label: '化粧',
}).then(res => {
effectList = res
});
sdk.getCommonFilter().then(res => {
filterList = res
})
})
sdk.on('cameraReady', async () => {
// cameraReadyコールバックでより早く出力画面を取得できますが、この時点では初期化時に設定した美顔パラメータはまだ適用されていません
// できるだけ早く画面を表示したい、かつ画面が表示されたときにすぐに美顔を適用しないシナリオに適します
// 美顔が有効になってもstreamを更新する必要はなく、SDK内部で既に処理済みです
const arStream = await ar.getOutput();
// ローカル再生
// localVideo.srcObject = arStream
})
sdk.on('ready', () => {
// readyコールバックで出力画面を取得すると、この時点で初期化時に設定した美顔パラメータが既に有効になっています
// 上記のcameraReadyでのoutputの取得と異なり、画面が表示されるとすぐに美顔を適用したい、かつ早く画面を表示しないシナリオに適します
// 必要に応じて選択
const arStream = await ar.getOutput();
// ローカル再生
// localVideo.srcObject = arStream
// readyコールバックでsetBeautify/setEffect/setFilterなどのレンダリングメソッドを呼び出します
sdk.setBeautify({
whiten: 0.3
});
sdk.setEffect({
id: effectList[0].EffectId,
intensity: 0.7
});
sdk.setEffect({
id: effectList[0].EffectId,
intensity: 0.7,
filterIntensity: 0.5 // 0.1.18以降ではeffect内のフィルターの強さを個別に設定可能。指定しない場合はデフォルトでエフェクトのintensityと一致します
});
sdk.setFilter(filterList[0].EffectId, 0.5)
})
// ジェスチャー認識を有効にした後、ジェスチャーの変化を検出したときにトリガーされます
sdk.on('handGesture',(hands)=>{
// 対応するhandの値はnone、thumb_up、thumb_down、victory、pointing_up、open_palm、iloveyou
})
// errorコールバック、sdkの使用に影響するエラーが発生した場合
sdk.on('error', (data)=>{
console.log('error', data.code, data.message)
})
// warningコールバック、SDKが処理時間の増加を検出した場合に警告を発します
sdk.on('warning', (data)=>{
console.log('warning', data.code, data.message)
})
イベント
説明
コールバックパラメータ
created
SDK認証完了時とインスタンス作成成功時にトリガー
-
cameraReady
SDKの画面生成時にトリガー、この時点でoutputには画面があるが美顔はまだ適用されていない
-
ready
SDK内部テスト初期化完了時にトリガー、この時点でoutput画面には美顔が適用され、新しいエフェクトを設定することもできる
-
error
SDKエラー発生時にトリガー
errorオブジェクト
warning
SDK警告発生時にトリガー
warningオブジェクト
handGesture
ジェスチャー認識を有効にした後、ジェスチャーの変化を検出したときにトリガーされる
認識されたジェスチャー
detectStatusChange
顔検出状態が変化したときにトリガー
Boolean、顔の認識の有無

オブジェクトメソッド

インターフェース
パラメータ
戻り値
説明
setBeautify(options)
type BeautifyOptions = {
whiten?: number; // 美白 0~1
dermabrasion?: number; // 美肌 0~1
lift?: number; // 細顔 0~1
shave?: number; // 小顔 0~1
eye?: number; // デカ目 0~1
chin?: number; // 顎 0~1
// 注意:以下のパラメータは1.0.11以降のバージョンでのみ使用可能です
darkCircle?: number; // クマ 0~1
nasolabialFolds?: number; // ほうれい線 0~1
cheekbone?: number; // 頬骨 0~1
head?: number; // 小頭 0~1
eyeBrightness?: number; // キラ目 0~1
lip?: number; // 唇 -1~1
forehead?: number; // 生え際 0~1
nose?: number; // 鼻 -1~1
usm?: number; // シャープネス 0~1
}
-
美顔パラメータを設定、美顔モジュールを有効にする必要があります。

setEffect(effects, callback, errCallback)
effects:エフェクトID | Effectオブジェクト | (エフェクトID | Effectオブジェクト) 配列
// Effectオブジェクト
type Effect = {
id: string; // エフェクトid
intensity: number; // エフェクト全体の強さ、値の範囲0~1、デフォルトで1
filterIntensity: number; // エフェクト内のフィルターの強さ、値の範囲0~1、デフォルトで1
};
callback:設定成功のコールバック
errCallback:失敗のコールバック
-
化粧、ステッカーエフェクトを設定、beautifyモジュールを有効にする必要があります
3D系エフェクトはプレミアム版Licenseのみサポート
setAvatar(params)
{
mode: 'AR' | 'VR',
effectId?: string, // effectIdパススルーで内蔵モデルを使用
url?: string, // urlパススルーでカスタムモデルを使用
backgroundUrl?: string, // 背景画像リンク、VRモードでのみ有効
}
-
アニ文字スタンプまたはバーチャルアバターを設定、beautifyモジュールを有効にする必要があります
プレミアム版Licenseのみサポート
setBackground(options)
{
type: 'image|video|blur|transparent', // 1.0.23以降はvideoタイプの動的背景をサポート
src: string, // image|videoタイプに必要
edgeBlur: number, // 1.0.25以降はサポート、値の範囲:0~10、エッジぼかし度を制御、値が小さいほどエッジの切り取りが鋭く、ぼかし度が低くなります。
}
-
背景の設定。Web版でsegmentationモジュールを有効にする必要があります
setForeground(options) (1.0.23バージョン以降サポート)
{
type: 'image|video',
src: string // リソースパス、base64またはオンラインアドレス
}
-
画面に固定されたフルスクリーン前景効果を設定
setSegmentationLevel(level)
level: 0 | 1 | 2
-
背景切り抜きモデルのレベルを切り替え
setFilter(id, intensity, callback, errCallback)
id:フィルターID
intensity:フィルター強さ、値の範囲0~1、デフォルトで1
callback:設定成功のコールバック
errCallback:失敗のコールバック
-
フィルターを設定
getEffectList(params)
{
PageNumber: number, // ページ、デフォルトで0
PageSize: number, // ページサイズ、デフォルトで1000
Name: '', // エフェクト名
Label: string | Array<string>, // エフェクトタグ、エフェクトタグリスト
Type: 'Custom' | 'Preset' // エフェクトタイプ、Custom-ユーザーカスタムエフェクト、Preset-内蔵エフェクト
}

エフェクトリスト
エフェクトリストを取得
getAvatarList(type)
type = 'AR' | 'VR' // AR-アニ文字、VR-バーチャルアバター
アニ文字/バーチャルアバターリスト

アニ文字/バーチャルアバターリストを取得
getEffect(effectId)
effectId:エフェクトID
単一エフェクト情報
指定されたエフェクトの情報を取得
getCommonFilter()
-
内蔵フィルターリスト
内蔵フィルターリストを取得
async initCore()
{
input?: MediaStream|HTMLImageElement|String; // 入力ソース
camera?: CameraConfig; // カメラモード
mirror?: boolean; // リバーサルミラー効果のオン・オフ
}
-
プリ初期化のみ使用でき、SDKに入力情報を提供します。詳細は読み込み最適化を参照してください
async updateInputStream(src, stopOldTracks) (0.1.19バージョン以降サポート)
src:新しい入力ストリームMediaStream
stopOldTracks: 古いMediaTrackの使用停止
-
入力メディアストリームを更新
updateInputImage(options) (1.0.24バージョン以降サポート)
{
width: number;// 画像レンダリングの高さ
height: number; // 画像レンダリングの幅
input: string;// 画像アドレス
}
-
入力画像を更新
async getOutput(fps:number,type:OUTPUT_TYPES, )
enum OUTPUT_TYPES {
IMAGE = 3,
MEDIA_STREAM = 4,
}
fps:出力メディアストリームのフレームレートの設定。デフォルトで入力メディアのfpsと同じです
type: 3 | 4
3-image、4-mediastream。入力が画像の場合、デフォルトで出力が3で、入力が画像以外の場合、デフォルトで出力が4です
MediaStream | String
Web側のみでサポート
disable()
-
-
顔検出を無効にし、未処理の元画像を返し、CPU使用率を下げることができます
enable()
-
-
顔検出を再開し、美顔などのエフェクトが適用された画面を返します
stop()
-
-
画面を一時停止し、画面が止まります
resume()
-
-
画面を再開し、画面を再生します
async takePhoto()
-
{
data: Uint8Array | Uint8ClampedArray,
width: number,
height: number
}
撮影インターフェース、bufferデータを含むオブジェクトを返し、
dataはImageData
async initLocalPlayer(id)
id: string // ローカルプレビュー用dom id
-
インターフェースはSDK出力効果をプレビューする便利なインターフェースを提供し、SDK出力のメディアストリームをvideoとして指定のdomコンテナで再生します
async resetCore(input)
input: MediaStream|HTMLImageElement|String; // 入力ソース
-
contextlostエラー発生時にこのインターフェースを呼び出して復元します
destroy()
-
-
現在のSDKインスタンスと関連テクスチャーリソースを破棄

エラー処理

errorコールバックで返されるオブジェクトにはエラーコードとエラー情報が含まれており、エラー処理に便利です。
sdk.on('error', (error) => {
// errorコールバックでエラーを処理
const {code, message} = error
...
})
エラーコード
意味
備考
10000001
現在のブラウザ環境は互換性がない
Chrome、Firefox、Safari、WeChatブラウザの使用を推奨します
10000002
現在のレンダリングコンテキストが紛失
-
10000003
レンダリング処理時間が長い
ビデオ解像度を下げるか一部機能を無効にすることを検討してください
10000005
入力ソース解析エラー
-
10000006
ブラウザ機能のサポートが不十分で、カクつくことがある
Chrome、Firefox、Safari、WeChatブラウザの使用を推奨します
10001101
エフェクト設定エラー
-
10001102
フィルター設定エラー
-
10001103
エフェクト強さパラメータが正しくない
-
10001104
sdk disabled状態、エフェクトを設定できない
-
10001105
無効なエフェクトID
-
10001201
カメラの起動に失敗
-
10001202
カメラ切断
-
10001203
カメラ権限を取得できない
カメラ権限を有効にする必要があり、設定→プライバシー→カメラで有効にしてください
10001204
メディアデバイスにアクセスできない(許可済み)
リクエストパラメータを満たすメディアタイプが見つからないか、システムエラーによりデバイスにアクセスできません
10001205
マイク権限を取得できない
マイク権限を有効にする必要があり、設定→プライバシーで有効にしてください
10001206
一部のブラウザではgetUserMediaインターフェースが返す幅と高さがユーザー設定と異なる場合がある
-
10004001
カメラ、マイク権限の問題を解決するにはページをリフレッシュする必要がある
-
20002001
認証パラメータが不足している
-
20001001
認証に失敗した
Licenseが作成されているか確認し、署名が正しいか確認してください
20001002
インターフェースリクエスト失敗
コールバックはインターフェースが返すデータを返します、詳細についてはインターフェースエラーコードをご参照ください
20001003
エフェクト設定インターフェース認証失敗
インターフェースにアクセスする権限がありません。基本版Licenseはプレミアム版License機能を使用できません
20001004
signatureタイムアウト
署名がタイムアウトで、再試行後もエラーが発生しました
20001005
authorizeタイムアウト
認証がタイムアウトで、再試行後もエラーが発生しました
40000000
未捕捉の例外
-
40000001
現在使用しているSDKバージョンが古すぎるため、一部のエフェクトが正しく表示されません。SDKバージョンをアップグレードしてください
-
50000002
解像度変更によりエフェクトが失われた
エフェクトを再設定する必要があります

警告処理

warningコールバックで返されるオブジェクトには警告コードと警告情報が含まれています。
sdk.on('warning', (warning) => {
// warningコールバックで警告を処理
const {code, message} = warning
...
})
警告コード
意味
備考
50005
検出処理時間が長すぎる
動的監視で、1フレームの処理時間が150msを超えると警告が発生します。これは、この時点でのレンダリングフレームレートが10fpsに達していないことを意味し、カクつきが発生しています。

現在のレンダリングコンテキスト喪失の処理

一部のPCでは、長時間バックグラウンドに切り替えるとcontextlostエラーの処理がトリガーされる場合があります。ArSdk.prototype.resetCore(input: MediaStream)でレンダリングコンテキストを復元できます。
sdk.on('error', async (error) => {
if (error.code === 10000002) {
const newInput = await navigator.mediaDevices.getUserMedia({...})
await sdk.resetCore(newInput)
}
})

ヘルプとサポート

この記事はお役に立ちましたか?

フィードバック