QQ群结束一起听歌

接口说明

强制结束指定 QQ 群当前正在进行的一起听歌活动，使该群恢复为普通群聊状态。适用于群管理或自动化脚本场景，例如在群内活动结束后由程序自动调用清理。调用成功时返回 ok。

调用地址

https://当前站点域名/api/qq/endlisten.php

该地址为本接口的完整对外调用地址，域名即本站对外提供的服务域名，路径部分原样使用，无需再做拼接或替换。若通过本站域名直接访问，路径以 /api/qq/endlisten.php 形式书写。

请求方式

本接口采用 GET 请求方式。

使用 GET 请求时，所有业务参数均以查询字符串（Query String）的形式附加在调用地址之后，一次请求即完成参数传递与结果返回，无需额外的请求体。参数名与参数值之间使用等号连接，多个参数之间使用与号分隔。

由于本接口为写操作且逻辑极为简单（仅按群号下发结束指令），使用 GET 方式可满足绝大多数调用场景；调用方在浏览器地址栏、curl 命令或 HTTP客户端中发起请求均可。

鉴权说明

本接口无需密钥。

调用时无需在地址中附加任何密钥参数，无需携带请求头令牌，也无需构造登录态或会话信息，直接以匿名身份访问调用地址即可完成调用。因此本接口不会因为缺少鉴权信息而返回鉴权失败类错误。

需要注意：无需密钥意味着任何持有调用地址的访问者都可触发该操作，请在正式环境中自行结合业务侧的访问控制、来源限制或频率控制措施，避免被非预期的请求滥用。

请求参数

本接口采用 GET 请求方式，全部参数通过 URL Query 传递，无需请求体。

参数取值说明

groupid

• 为纯数字的 QQ 群号，不含空格、前缀或后缀。
• 可为普通 QQ 群号或频道关联的群号，只要该群当前存在正在进行的「一起听歌」活动即可。
• 群号需完整准确；若该群无一起听歌活动，或当前机器人账号不在该群内，则无法执行结束操作。

请求示例

/api/?groupid=10001

成功响应示例

请求成功后，接口以纯文本形式返回固定结果 ok，不包含 JSON 包装结构。

ok

HTTP 状态为 200，响应体即上例文本。若结束操作未成功执行，则不会返回该内容。

响应字段说明

说明：

• 返回 ok 即代表结束指令已生效，该群当前的一起听歌任务被终止。
• 该接口无需密钥，调用成功后不返回群号、任务 ID、剩余时长等附加信息；若需确认结果，可再次查询该群一起听歌状态。
• 免费接口，无返回计费或配额字段。

错误响应示例

本接口在业务处理成功时返回 ok 文本；一旦校验或执行失败，则统一返回如下 JSON 结构（HTTP 状态码为 200，由 errcode 字段表达具体错误）：

{"code":0,"msg":"未提供调用密钥","errcode":11001}

常见错误响应示例：

响应字段说明：

业务错误码说明

本接口为免费接口、无需密钥，因此 11001～11012 及11019～11024 等与密钥、积分、频率限制相关的错误码在正常调用中不会出现；实际调用时重点关注 11018（请求方式或参数不符合要求）、11013（接口不存在）以及 11014～11017（服务端链路与服务可用性相关）这几类错误。出现 11017 时可稍后重试；持续返回同一 errcode 时，请对照上表检查请求地址与参数是否与接口资料一致。

调用示例

资料未给出固定域名，下方示例统一以 SITE_DOMAIN 代表当前站点实际域名，调用时替换为本站对外域名即可。请求方式为 GET，无需密钥，参数直接放在 Query 中。

终端 curl（bash）

# 结束群10001 的一起听歌（无需密钥）
SITE_DOMAIN="当前站点域名"

curl -s -X GET "https://${SITE_DOMAIN}/api/qq/group-end-listen?groupid=10001"

正常返回：ok

PHP

// PHP 调用示例：结束 QQ 群一起听歌（无需密钥，无需额外请求头）
// 使用前将 SITE_DOMAIN 替换为本站实际域名
const SITE_DOMAIN = '当前站点域名';

function endGroupListen(int $groupId): string
{
    $url = sprintf(
        'https://%s/api/qq/group-end-listen?%s',
        SITE_DOMAIN,
        http_build_query(['groupid' => $groupId])
    );

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
    ]);

    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($body === false) {
        throw new RuntimeException('请求失败，HTTP 状态码：' . $code);
    }

    return trim($body);
}

echo endGroupListen(10001); // 输出：ok

注意事项

• 无需密钥：本接口为免密钥调用，直接以 GET 方式请求本站提供的完整地址即可，不要额外附加任何鉴权参数或请求头；若请求中携带了无关的密钥字段，忽略即可。
• 请求地址：请使用本站文档给出的完整接口路径并拼接当前站点域名后访问，请统一使用 HTTPS 加密传输，避免明文 HTTP 请求被中间环节篡改或截获。
• groupid 为必填：目标群号必须以整数形式传入，不可省略、不可传空字符串或 null；缺失或格式非法将无法定位目标群，导致请求失败。
• 群号取值范围：请传入真实的、被操作者所在的有效 QQ 群号，不要填写 QQ 号、频道号或其他业务标识；示例值 10001 仅为占位说明，直接照抄会操作到非预期群。
• 参数编码：虽然请求参数为数字型，但若拼接在查询字符串中，仍需保证 URL 合法、编码正确，避免出现多余空格、换行或重复的 groupid 参数。
• 接口语义为“强制结束”：调用成功后目标群的一起听歌状态会被立即终止，属于不可回退的操作。请在确认群号无误后再发起请求，切勿将其放入循环、定时任务或前端页面的重复触发逻辑中。
• 频率限制：本接口免费开放，但仍受站点整体请求频率策略约束。批量处理多个群时请在请求之间加入合理间隔，避免短时间大量并发；若返回失败结果，请稍后重试而不是立即高频重发。
• 权限与责任：调用方须确保对目标群具备相应的管理或操作权限，并遵守平台使用规则；本接口仅接受对目标群一起听歌状态的结束请求，不返回群内业务数据。
• 返回值说明：成功时返回 ok 文本，表示结束指令已下发；请以此作为成功判据，不要对返回内容做额外解析。返回非 ok 时请检查群号是否有效、请求方式是否为 GET、地址是否正确。
• 幂等与重复调用：对已结束的一起听歌再次调用不会恢复任何状态，只会重复下发无效指令，因此无需也不建议为同一群号反复调用。