yttAPI 官方文档与 WordPress 集成指南 - 免费随机图片 API

什么是 yttAPI？

yttAPI 是一个完全免费的随机图片 API 服务，由 yttAPI 维护，基于自有 5GB+ 图库，提供稳定的随机图片访问服务。所有图片以 WebP 格式提供，体积小、加载快。接口风格完全兼容知名的 LoliAPI，上手几乎零成本。

目前该服务提供了三大类接口：

接口类型	请求地址	适用场景
双端自适应随机图片	`https://api.m1f.cn/acg/`	自动适配电脑/手机/平板
电脑端随机图片	`https://api.m1f.cn/acg/pc/`	横屏桌面壁纸
手机端随机图片	`https://api.m1f.cn/acg/pe/`	竖屏手机壁纸

核心参数说明

yttAPI 的请求参数非常灵活，核心参数如下：

参数	可选值	说明
`id`	整数	指定图片 ID
`type`	`url`（默认）/ `img` / `json`	返回方式：`url` 为 302 重定向（性能最佳）；`img` 直接返回图片二进制（WordPress 推荐）；`json` 返回图片元数据
`device`	`pc` / `mobile` / `tablet`	显式指定设备分支，覆盖 UA 自适应

⚠️ 用户注意：官方文档特别建议使用 type=img 方式，可以解决部分客户端不跟随 302 重定向的问题。

WordPress 集成实战

场景一：文章特色图片自动填充

在主题的 functions.php 中添加以下代码，当文章没有设置特色图片时，自动从 yttAPI 获取一张随机图：

function auto_set_featured_image() {
    global $post;
    if (has_post_thumbnail($post->ID)) {
        return;
    }
    // 请求随机图片（直接返回二进制）
    $api_url = 'https://api.m1f.cn/acg/?type=img';
    $image_data = file_get_contents($api_url);
    if ($image_data) {
        $upload_dir = wp_upload_dir();
        $filename = 'featured-' . uniqid() . '.webp';
        $filepath = $upload_dir['path'] . '/' . $filename;
        file_put_contents($filepath, $image_data);
        $attachment = array(
            'post_mime_type' => 'image/webp',
            'post_title' => '随机配图',
            'post_content' => '',
            'post_status' => 'inherit'
        );
        $attach_id = wp_insert_attachment($attachment, $filepath, $post->ID);
        require_once(ABSPATH . 'wp-admin/includes/image.php');
        $attach_data = wp_generate_attachment_metadata($attach_id, $filepath);
        wp_update_attachment_metadata($attach_id, $attach_data);
        set_post_thumbnail($post->ID, $attach_id);
    }
}
add_action('publish_post', 'auto_set_featured_image');

场景二：响应式主题适配

对于响应式 WordPress 主题，可以利用 device 参数按设备输出不同尺寸的图片：

function get_random_image_by_device() {
    $device = wp_is_mobile() ? 'mobile' : 'pc';
    return 'https://api.m1f.cn/acg/?device=' . $device . '&type=img';
}

在模板中直接调用：

场景三：获取图片 JSON 元数据

如果需要图片的宽高、分类等信息，可以使用 type=json 模式：

$api_url = 'https://api.m1f.cn/acg/?type=json';
$response = file_get_contents($api_url);
$data = json_decode($response, true);
// 返回示例：
// {
//   "code": 0,
//   "site": "api.m1f.cn",
//   "imgurl": "https://api.m1f.cn/img/pc/img23.webp",
//   "width": "2048",
//   "height": "1152",
//   "category": "pc"
// }

拿到这些数据后，可以用于构建更丰富的图片展示效果，比如根据图片比例自适应布局。

场景四：用户默认头像

很多 WordPress 站点使用 Gravatar，但新用户没有头像时显示空白很影响体验。可以在 functions.php 中添加：

add_filter('avatar_defaults', 'add_random_avatar');
function add_random_avatar($avatar_defaults) {
    $avatar_defaults['https://api.m1f.cn/acg/?type=img'] = '随机二次元头像';
    return $avatar_defaults;
}

请求示例速查

需求	请求地址
最基本调用（返回随机图片）	`https://api.m1f.cn/acg/`
WordPress 推荐方式（直接返回图片二进制）	`https://api.m1f.cn/acg/?type=img`
获取指定 ID 图片的 JSON 数据	`https://api.m1f.cn/acg/?id=23&type=json`
强制桌面端图片（响应式主题）	`https://api.m1f.cn/acg/?device=pc&type=img`
电脑端专用接口	`https://api.m1f.cn/acg/pc/`
手机端专用接口	`https://api.m1f.cn/acg/pe/`