---
name: "processPetForegroundMediaByTemplate"
mode: "kit"
versionRequirements:
  - { name: "AIKit", version: "1.4.3" }
  - { name: "@ray-js/ray", version: "1.7.27" }
platform:
  - "iOS"
  - "Android"
async: true
title: "processPetForegroundMediaByTemplate - 通过模板进行媒体前景视频处理"
---

## processPetForegroundMediaByTemplate

> [VERSION] AIKit >= 1.4.3 | @ray-js/ray >= 1.7.27

> [PLATFORM] iOS, Android

> ⚡ **支持 Promise 调用** — 不传 success / fail / complete 回调时，该方法返回 Promise。

### 描述

基于模板进行宠物前景媒体合成处理

### 参数

| 属性 | 类型 | 必填 | 默认值 | 最低版本 | 描述 |
| --- | --- | --- | --- | --- | --- |
| `templateObject` | `ForegroundMediaTemplateObject` | 是 | - | `1.4.3` | 模板对象 |
| `mediaSource` | `string` | 是 | - | `1.4.3` | 输入媒体数据源 |
| `outputConfig` | `OutputConfig` | 否 | - | `1.4.3` | 输出配置 |
| `extendParam` | `Record<string, any>` | 否 | - | `1.4.3` | 扩展参数 |
| `complete` | `() => void` | 否 | - | - | 接口调用结束的回调函数（调用成功、失败都会执行） |
| `success` | `(params: Object) => void` ↓见下方 | 否 | - | - | 接口调用成功的回调函数 |
| `fail` | `(params: Object) => void` ↓见下方 | 否 | - | - | 接口调用失败的回调函数 |

#### success 回调参数

| 属性 | 类型 | 最低版本 | 描述 |
| --- | --- | --- | --- |
| `outputPath` | `string` | `1.4.3` | 输出前景媒体的路径 |
| `extData` | `Record<string, any>` | `1.4.3` | 扩展数据 |

#### fail 回调参数

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `errorMsg` | `string` | 错误信息 |
| `errorCode` | `string \| number` | 错误码 |
| `innerError` | `Object` | 错误扩展 |

##### fail(params).innerError 的属性

| 属性 | 类型 | 描述 |
| --- | --- | --- |
| `errorCode` | `string \| number` | 错误扩展码 |
| `errorMsg` | `string` | 错误扩展信息 |


### 引用对象

##### `interface` ForegroundMediaTemplateObject

| 属性 | 类型 | 最低版本 | 描述 |
| --- | --- | --- | --- |
| `type` | `string` | `1.3.2` | 模板类型，来源于云端 |
| `effect` | `ForegroundMediaTemplateEffectObject` | `1.3.2` | 模板特效对象 |
| `extendParam` | `Record<string, any>` | `1.3.2` | 扩展参数 |

##### `interface` OutputConfig

| 属性 | 类型 | 最低版本 | 描述 |
| --- | --- | --- | --- |
| `path` | `string` | `1.3.2` | 输出前景媒体的路径 |
| `name` | `string` | `1.3.2` | 输出前景媒体的文件名 |
| `min_duration` | `number` | `1.3.2` | 输出前景媒体的最小时长，单位为秒 |
| `outputType` | `string` | `1.4.3` | 输出类型，支持 image、audio、video，默认为 image |
| `extendParam` | `Record<string, any>` | `1.3.2` | 扩展参数 |

##### `interface` ForegroundMediaTemplateEffectObject

| 属性 | 类型 | 最低版本 | 描述 |
| --- | --- | --- | --- |
| `code` | `string` | `1.3.2` | 特效编码 |
| `name` | `string` | `1.3.2` | 特效名称 |
| `ouputDuration` | `number` | `1.3.2` | 已废弃，请使用 outputDuration |
| `outputDuration` | `number` | `1.4.3` | 特效输出时长，单位为秒 |
| `outputType` | `string` | `1.4.3` | 特效输出类型，支持 image、audio、video，默认为 image |
| `image` | `string` | `1.3.2` | 特效预览图 URL |
| `resource` | `string` | `1.3.2` | 特效资源 URL |
| `extendParam` | `Record<string, any>` | `1.3.2` | 扩展参数 |


### 示例代码

#### 基础调用

```tsx
import { ai } from '@ray-js/ray'

const { processPetForegroundMediaByTemplate } = ai;

processPetForegroundMediaByTemplate({
  templateObject: { type: 'example', effect: { code: 'example', name: 'example', ouputDuration: 0, outputDuration: 0, image: 'example', resource: 'example' } },
  mediaSource: 'example',
  success: (result) => {
    console.log('processPetForegroundMediaByTemplate success', result);
  },
  fail: (error) => {
    console.log('processPetForegroundMediaByTemplate fail', error.errorMsg);
  },
});
```