美图WEB开放平台

API说明

美图秀秀开放插件包含美图秀秀M1(完整版)、美图秀秀M2(美化图片)、美图秀秀M3(拼图)及美图秀秀M4(头像编辑器),我们已经对四个版本进行整合,提供一致的接口供您调用。

1、环境配置

1.1、设置crossdomain.xml

下载crossdomain.xml文件,把解压出来的crossdomain.xml文件放在您保存图片或图片来源的服务器根目录下,
比如: http://example.com.cn,那么crossdomain.xml的路径为:http://example.com.cn/crossdomain.xml。
需要注意的是crossdomain.xml必须部署于站点根目录下才有效, crossdomain.xml的目的是授权来自美图域下的flash向您的站点上传图片或者从您的站点加载图片。
【备注】由于本地测试会被flash安全沙箱拦住,请自行搭建web服务器,在web 环境中测试。

1.2、调用方法

1.2.1、引用JS代码

在你的网页代码head标签里或者body标签里加入代码。

<script src="http://open.web.meitu.com/sources/xiuxiu.js" type="text/javascript"></script>

1.2.2、使用演示(demo),快速上手

1.2.3、如需更详尽文档解释,可到开发博客查阅。


2、API列表

2.1、方法

2.1.1、 嵌入SWF(xiuxiu.embedSWF)

功能描述:网页中嵌入美图秀秀的编辑器
语法:

xiuxiu.embedSWF(container,editorType,width,height,id);
参数 必选 字段类型 说明
container string 要被flash替换的容器的id
editorType int 要嵌入的编辑器类型(1为轻量编辑,2为轻量拼图,3为完整版,5为头像编辑器,默认值1)
width string 编辑器宽度(可以为数字或者百分比,对轻量编辑和完整版有效)
height string 编辑器高度(可以为数字或者百分比,对轻量编辑和完整版有效)
id string 编辑器在页面中的id,默认值为" xiuxiuEditor"(当需要在同一个页面内嵌入一个以上编辑器
时需要以不同的id来区分,这时候就很有用,在接下去的几个接口中便可通过不同的id调用不
同编辑器的接口(demo))

示例代码

xiuxiu.embedSWF("altContent", 3, 800, "100%","lite");

2.1.2、 加载图片(xiuxiu.loadPhoto)

功能描述:编辑器载入图片
语法:

xiuxiu.loadPhoto(images,base64,id);
参数 必选 字段类型 说明
images string或者array 在编辑器中载入图片,类型可以为字符串或数组,也就是说可以同时载入一张到多张图片
(需要注意的是,1.如果是数组,数组中元素必须是同一类型图片,要么都是base64
类型的,要么是url;2.如果是base64图片,需要去掉几个头字符,只保留纯图片数据,
例如去掉" data:image/jpeg;base64,")
base64 boolean 是否是base64图片,默认值为false
id string 编辑器在页面中的id,默认值为" xiuxiuEditor"

示例代码

单张图片:
xiuxiu.loadPhoto("http://open.web.meitu.com/sources/images/1.jpg");
单张base64的图片(demo):
xiuxiu.loadPhoto("/9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja…", true); 
多张图片(demo):
xiuxiu.loadPhoto(["http://open.web.meitu.com/sources/images/1.jpg"]);
多张base64的图片:
xiuxiu.loadPhoto(["/9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja…"], true);

2.1.3、上传URL(xiuxiu.setUploadURL)

功能描述:设置上传接口地址,接收图片的地址
语法:

xiuxiu.setUploadURL (url,id);
参数 必选 字段类型 说明
url string 设置上传接口地址(必须为绝对路径)
id string 编辑器在页面中的id,默认值为" xiuxiuEditor"

示例代码

xiuxiu.setUploadURL("http://web.upload.meitu.com/image_upload.php"); //修改为您自己的上传接收图片程序

2.1.4、设置参数(xiuxiu.setUploadArgs)

功能描述:设置上传参数(如无需上传参数可不调用)
语法:

xiuxiu.setUploadArgs (args,id);
参数 必选 字段类型 说明
args object 设置上传参数
id string 编辑器在页面中的id,默认值为" xiuxiuEditor"

示例代码

xiuxiu.setUploadArgs({a:1, b:"lucky"});

2.1.5、设置上传类型(xiuxiu.setUploadType)

功能描述:设置上传方式(以下流式和表单上传都是POST请求方式)
语法:

xiuxiu.setUploadType (uploadType,id);
参数 必选 字段类型 说明
uploadType int 设置上传方式
1、流式上传(demo)
Content-type:application/octet-stream;
2、标准表单上传(demo)
Content-type:multipart/form-data;
3、为编码成Base64传给JS,详细可参看下文的xiuxiu.onSaveBase64Image事件(demo)
默认上传方式为流式上传,只有上传方式为表单上传才需调用此函数
关于octet-stream上传方式的接收代码可参阅 http://www.5iphp.com/php-input
关于multipart/form-data 上传方式的接收代码可参阅 http://www.w3school.com.cn/php/php_file_upload.asp
php示例可参考 流式上传 或者 标准表单上传
C#示例可参考 流式上传 或者 标准表单上传
JSP示例可参考 流式上传 或者 标准表单上传
id string 编辑器在页面中的id,默认值为" xiuxiuEditor"

示例代码

xiuxiu.setUploadType(2);

备注:美图秀秀提供两个上传接口供测试
一个是octet-stream方式上传,地址为:http://imgkaka.meitu.com/xiuxiu_web_pic_save.php
另一个是multipart/form-data方式上传,地址为:http://web.upload.meitu.com/image_upload.php
表单名称为"upload_file"。

2.1.6、设置表单名称(xiuxiu.setUploadDataFieldName)

功能描述:设置在上载 POST 操作中位于文件数据之前的字段名
也就是对应于设置html<input type="file" name="Filedata" id="file" />中的name
语法:

xiuxiu.setUploadDataFieldName (uploadDataFieldName,id);
参数 必选 字段类型 说明
uploadDataFieldName string 仅对表单上传有效(如果使用表单上传且字段名不为"Filedata"才需调用此函数)
id string 编辑器在页面中的id,默认值为" xiuxiuEditor"

示例代码

xiuxiu.setUploadDataFieldName("Filedata");

如果以上事件还不能满足您的需求,请查看高级方法。
点击显示高级方法

2.1.7、高级参数设置(xiuxiu.setLaunchVars)

功能描述(高级功能):设置flash初始化参数来实现更多高级功能,请在xiuxiu.embedSWF之前调用此函数,否则无法生效。
语法:

xiuxiu.setLaunchVars(key, value);
参数 必选 字段类型 说明
key string 参数名
value String /Boolean/Number 参数值

示例代码

xiuxiu.setLaunchVars("quality", 90);

下表为可设置的属性列表

参数 字段类型 可能的值 说明
cropPresets string/array 设置裁剪的比例或尺寸;具体有关此参数完整设置,请参阅
cropPresets详细参数设置
nav string 自动导航到某个功能块,例如完整版需要导航到照片拼接(demo),可以 xiuxiu.setLaunchVars ("nav", "puzzle/puzzlePhoto");有关此参数完整设置,请参阅
nav详细参数设置
customMenu array 设定自定义菜单,根据你的需要自行组合功能(demo)。有关此参数完整介绍,请参阅 customMenu详细参数设置。(目前只对M1完整版有效)
customMaterial string 自定义素材,根据你的网站的具体业务需求,在美图秀秀内展现跟您网站相关的素材(demo)。有关此参数完整介绍,请参阅 customMaterial详细参数设置。(目前只对M1完整版有效)
localFileEnabled int 0或者1 是否支持打开本地文件(目前只对轻量编辑器有效)
uploadBtnLabel string 上传按钮的文本标签
titleVisible int 0或者1 是否显示标题栏(仅对轻量编辑及轻量拼图有效)
maxFinalWidth int 设置生成的图片的最大宽度,图片在此宽度内按比例缩放,如无需设置最大宽度,可设为0(仅对轻量编辑、拼图、头像编辑有效)
maxFinalHeight int 设置生成的图片的最大高度,图片在此高度内按比例缩放,如无需设置最大高度,可设为0(仅对轻量编辑、拼图、头像编辑有效)
quality int 1到100(默认值为90) 设置生成图片的质量(仅对轻量编辑、拼图、头像编辑有效)
preventBrowseDefault int 0或者1 是否取消默认打开行为(当取消默认打开行为时,点击打开按钮则调度xiuxiu.onBrowse事件,可在此事件内弹出照片选择器。适用场景:当您的网站有相册系统时,需要点击打开图片按钮的时候,可以弹出自定义的照片选择器来从中选取照片(demo1,demo2),需要注意的是,如果照片选择器被flash盖住,可以设置flash为透明模式,即xiuxiu.params.wmode = "transparent";)
preventUploadDefault int 0或者1 是否取消默认上传行为(当取消默认上传行为时,点击上传按钮则调度xiuxiu.onUpload事件)

2.1.8、高级参数设置--上传(xiuxiu.upload)

功能描述:上传,此方法极少用到,一般来说已经有了默认上传行为,就无需再外部调用进行上传(仅对轻量编辑器、轻量拼图、头像编辑器有效

语法:

xiuxiu.upload (url,uploadArgs,type,id);
参数 必选 字段类型 说明
url string 上传接口地址
uploadArgs object 上传参数
type int 上传方式/(值为1或者3)
id string 编辑器在页面中的id,默认值为"xiuxiu.Editor"

适用场景: 1.点击保存按钮时弹出自定义的文件浏览对话框,用户选择要保存的目录后,调用编辑器上传进口进行上传(demo)。

示例代码

xiuxiu.setLaunchVars("preventUploadDefault", 1);
xiuxiu.embedSWF("altContent2", 1, 700, 500, "lite");
xiuxiu.setUploadURL("xxx");

xiuxiu.onUpload = function (id)
{
    //这里弹出自定义文件浏览对话框
}

//用户选择要保存的目录后
	xiuxiu.upload ();
 

2.2、事件

2.2.1、初始化(xiuxiu.onInit)

xiuxiu.onInit = function(id) {}

当编辑器初始化完成时调用,必须定义一个在调用事件处理函数时执行的函数。

参数 说明
id 调度此事件的编辑器在页面中的id

示例代码

xiuxiu.onInit = function (id)
{
	// your code here
	alert("flash初始化完成");
}

2.2.2、图片上传前(xiuxiu.onBeforeUpload)

xiuxiu.onBeforeUpload = function(data, id) {}

在图片上传前调用,提供上传前最后一个机会来改变上传数据甚至终止上传,如果需要终止上传,只要返回false,需要继续上传则返回true;同时data参数为object类型,包含要上传的图片的属性,如宽度、高度、文件名、字节数等。

参数
data:要上传的图片的属性(object类型,下表为data包含的属性)

属性 字段类型 说明
width int 图片宽度
height int 图片高度
type string 格式(目前只有jpg、png、gif)三种
size int 图片字节数
name string 图片名称
numOperate int 打开编辑器之后编辑的第几张图片
isNet booleam 是否是网络图片
url string 如果是网络图片,则为图片url,否则为空

参数
id:调度此事件的编辑器在页面中的id

适用场景:
1.论坛上传图片最大为2M,因此可在上传前检查图片大小,超过则进行提示不再上传。(demo)

示例代码

xiuxiu.onBeforeUpload = function (data, id)
{
  var size = data.size;
  if(size > 2 * 1024 * 1024)
  { 
    alert("图片不能超过2M"); 
    return false; 
  }
  return true; 
}

2.图片上传前重新更新上传参数(demo)

示例代码

xiuxiu.setUploadArgs({c:1, d:"test" }, id);
xiuxiu.onBeforeUpload = function (data, id)
{
  xiuxiu.setUploadArgs({c:1111, d:"goodluck" }, id);
  return true;
}

2.2.3、上传响应(xiuxiu.onUploadResponse)

xiuxiu.onUploadResponse= function(data,id) {}

当上传图片后端响应时调用,必须定义一个在调用事件处理函数时执行的函数。

参数
data:服务器端返回的数据
id:调度此事件的编辑器在页面中的id

示例代码

xiuxiu.onUploadResponse = function (data)
{
	alert("上传响应" + data);
}

2.2.4、关闭编辑器(xiuxiu.onClose)

xiuxiu.onClose = function(id) {}

当在flash中点击关闭按钮时调用,必须定义一个在调用事件处理函数时执行的函数。

参数
id:调度此事件的编辑器在页面中的id

示例代码

xiuxiu.onClose = function (id)
{
	alert("编辑器关闭");
}

2.2.5、调试编辑器(xiuxiu.onDebug)


xiuxiu.onDebug= function(data,id) {}
		

当发生错误时输出的调试信息,必须定义一个在调用事件处理函数时执行的函数。

参数
data:调试信息
id:调度此事件的编辑器在页面中的id

示例代码

xiuxiu.onDebug = function (data)
{
	alert("错误响应" + data);
}

错误代码及其意义

错误代码 描述
MT0001 上传接口不存在(404)
MT0002 您的服务器没有crossdomain.xml,
或者crossdomain.xml内未含有<allow-access-from domain="*.meitu.com"/>
查看crossdomain.xml如何设置
MT0003 上传接口未设置

如果以上事件还不能满足您的需求,请查看高级事件。
点击显示高级事件

2.2.6、高级事件

2.2.6.1、点击打开图片按钮(xiuxiu.onBrowse)

xiuxiu.onBrowse= function(channel, multipleSelection, canClose, id) {}

当取消默认打开行为后,在flash中点击打开图片按钮时调用。必须定义一个在调用事件处理函数时执行的函数。 当您的网站有相册系统时,需要点击打开图片按钮的时候,可以弹出自定义的照片选择器来从中选取照片,这时候这个事件就非常有用。需要注意的是必须取消默认打开行为,即xiuxiu.setLaunchVars("preventBrowseDefault", 1);(demo)

参数
channel:编辑器中调度此事件的来源
multipleSelection:是否可多选
canClose:自定义文件浏览对话框能否关闭
id:调度此事件的编辑器在页面中的id

示例代码

xiuxiu.onBrowse = function (channel, multipleSelection, canClose, id)
        	{
        		alert("打开自定义照片选择器");
        	}

2.2.6.2、保存为base64图片触发时(xiuxiu.onSaveBase64Image)

xiuxiu.onSaveBase64Image= function(data, fileName, fileType, id) {}

当文件不进行流式或者表单形式上传,而是进行Base64编码后传给JS使用时调用。必须定义一个在调用事件处理函数时执行的函数。 当您的网站使用编辑器处理完照片后需要把这张图片传给其他程序来做后续处理,而又不想重复上传,这时候这个事件就非常有用。需要注意的是需要设置上传类型为3,即xiuxiu.setUploadType(3);(demo)

参数
data:Base64编码的图片
filename:文件名
fileType:文件格式
id:调度此事件的编辑器在页面中的id

示例代码

xiuxiu.onSaveBase64Image= function (data, fileName, fileType, id)
        	{
        		alert("保存Base64编码的图片");
        	}

2.2.6.3、点击上传按钮(xiuxiu.onUpload)

xiuxiu.onUpload = function(id) {}

当取消默认上传行为后,在flash中点击上传按钮时调用。必须定义一个在调用事件处理函数时执行的函数。 当需要在保存前中断,然后弹出文件浏览对话框让用户选择要保存的地方或者让用户做其他自定义操作,这时候这个事件就非常有用。需要注意的是必须取消默认上传行为,即xiuxiu.setLaunchVars("preventUploadDefault", 1);,用户操作完之后,调用xiuxiu.upload();继续上传(demo)。

2.2.6.4、批量上传过程中,当前图片上传响应时(xiuxiu.onBatchUploadResponse)

xiuxiu.onBatchUploadResponse = function (data, index, id) {}

批量上传过程中,每一张图片上传后都会调度此事件一次。
必要时你可以对此事件进行处理,根据参数data决定下面剩余的图片是否继续上传,
如需终止上传,则需返回一个object类型的返回值{"continue":false},如需继续上传,则返回{"continue":true},
如果上传成功(缩略图上打钩)则返回{"continue":true,"success":true},同理上传不成功返回{"continue":true,"success":false}(demo)

参数
data:服务器端返回的数据(字符型)
index:当前上传完成的图片的索引
id:调度此事件的编辑器在页面中的id

示例代码

xiuxiu.onBatchUploadResponse = function (data, index, id)
        	{
        		var returnValue = {"continue":true};
                        return returnValue;
        	}

2.2.6.5、批量上传全部完成时(xiuxiu.onBatchUploadComplete)

xiuxiu.onBatchUploadComplete= function(id) {}

图片全部处理并上传完成时调度此事件。必要时你可以对此事件进行处理,进行页面跳转或关闭编辑器。

参数
id:调度此事件的编辑器在页面中的id

示例代码

xiuxiu.onBatchUploadComplete= function (id)
        	{
        		//图片全部上传完成,接下去自行处理
        		alert("图片全部上传完成,接下去自行处理");
        	}