取消请求与任务

在调用哈基米 API 进行大模型对话或多媒体异步生成时，若用户需要终止请求，可以参考本篇文档。主要分为**流式对话请求的取消（实时连接中断）和异步生成任务的取消（主动调用接口）**两部分。

---

1. 取消流式对话请求 (Chat Completions)

对于标准的聊天对话接口（例如 /v1/chat/completions），请求通常是同步进行的。特别是在开启流式传输（stream: true）时，客户端是通过 Server-Sent Events (SSE) 长连接持续接收响应的。

取消原理

无需调用单独的 API 接口。 客户端只需要在需要中止时主动关闭或断开 HTTP/TCP 连接（例如使用客户端的 Abort 机制）。 哈基米 API 站的服务端会实时监听客户端的断开事件。一旦检测到客户端主动关闭了连接（Client Disconnect），平台将会：

1. 立即中止向上游大模型渠道的请求，避免上游继续生成造成浪费。
2. 触发实时结算，仅扣除已生成部分的 Token 额度，未生成的 Tokens 将不予计费。

代码示例 (前端 JavaScript / TypeScript)

在 Web 前端开发中，推荐使用原生的 AbortController 机制来取消正在进行中的流式请求。

JavaScript - Fetch

const controller = new AbortController();
const signal = controller.signal;

async function startChat() {
  try {
    const response = await fetch('https://api.gemai.cc/v1/chat/completions', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk-你的令牌',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: '[官逆]gemini-2.5-pro',
        messages: [{ role: 'user', content: '请帮我写一篇关于人工智能发展史的5000字长文。' }],
        stream: true
      }),
      signal: signal // 将 abort 信号绑定 to 请求上
    });

    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      
      const chunk = decoder.decode(value);
      console.log(chunk); // 持续接收流式输出
    }
  } catch (error) {
    if (error.name === 'AbortError') {
      console.log('请求已被用户成功取消！');
    } else {
      console.error('请求发生错误：', error);
    }
  }
}

// 在需要取消对话（例如用户点击了“停止生成”按钮）时调用：
function stopChat() {
  controller.abort(); // 主动发出取消信号，断开连接
}

Python - Requests

import requests
import time

try:
    # 使用 stream=True 进行流式请求
    response = requests.post(
        'https://api.gemai.cc/v1/chat/completions',
        headers={
            'Authorization': 'Bearer sk-你的令牌',
            'Content-Type': 'application/json'
        },
        json={
            'model': '[官逆]gemini-2.5-pro',
            'messages': [{'role': 'user', 'content': '请帮我写一篇关于人工智能发展史的5000字长文。'}],
            'stream': True
        },
        stream=True
    )
    
    # 模拟在接收前几段响应后由于某种原因决定取消
    for i, line in enumerate(response.iter_lines()):
        if line:
            print(line.decode('utf-8'))
        
        # 接收 5 条消息后主动退出循环并关闭连接
        if i >= 5:
            print("主动中止连接...")
            response.close() # 关闭响应，断开连接
            break
            
except Exception as e:
    print("发生错误：", e)

---

2. 取消异步生成任务 (Video/Image Tasks)

对于异步任务接口（例如 Sora、Luma 等视频生成任务 /v1/videos），提交任务后会立刻返回一个任务 ID，并进入排队（queued）或生成中（processing）。由于这一过程不再依赖初始的 HTTP 提交连接，用户需要通过主动调用取消接口来中止任务。

重要提示 (关于中转平台兼容性)

New API / One API 中转平台目前可能无法很好地转发非标准的 DELETE 取消路由。 如果您是通过中转平台分发服务调用的，为了确保取消请求能直达底层，请务必直接向本站地址 https://api.gemai.cc 发起取消请求。

接口一：DELETE 方式取消 (推荐)

向正在排队或处理的任务 ID 发送 DELETE 请求，即可执行任务中止。

接口信息

项目	值
方法	DELETE
路径	/v1/videos/{id}
示例地址	https://api.gemai.cc/v1/videos/video_task_xxx
鉴权	Authorization: Bearer sk-你的令牌

请求示例

cURL

curl -X DELETE 'https://api.gemai.cc/v1/videos/video_task_xxx' \
  --header "Authorization: Bearer $GEMAI_API_KEY"

JavaScript

const taskId = 'video_task_xxx';
const response = await fetch(`https://api.gemai.cc/v1/videos/${taskId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${process.env.GEMAI_API_KEY}`
  }
});

console.log(await response.json());

Python

import os
import requests

response = requests.delete(
    'https://api.gemai.cc/v1/videos/video_task_xxx',
    headers={'Authorization': f"Bearer {os.environ['GEMAI_API_KEY']}"}
)

print(response.json())

返回示例

{
  "id": "video_task_xxx",
  "object": "video.deleted",
  "deleted": true
}

---

接口二：POST 方式取消

若您的调用环境（部分低版本客户端、网关或库）不支持或限制了 DELETE 请求，哈基米 API 同时提供了 POST 形式的兼容端点。

接口信息

项目	值
方法	POST
路径	/v1/video/generations/{task_id}/cancel
示例地址	https://api.gemai.cc/v1/video/generations/task_abc123/cancel
鉴权	Authorization: Bearer sk-你的令牌

请求示例

cURL

curl -X POST 'https://api.gemai.cc/v1/video/generations/task_abc123/cancel' \
  --header "Authorization: Bearer $GEMAI_API_KEY"

JavaScript

const taskId = 'task_abc123';
const response = await fetch(`https://api.gemai.cc/v1/video/generations/${taskId}/cancel`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.GEMAI_API_KEY}`
  }
});

console.log(await response.json());

Python

import os
import requests

response = requests.post(
    'https://api.gemai.cc/v1/video/generations/task_abc123/cancel',
    headers={'Authorization': f"Bearer {os.environ['GEMAI_API_KEY']}"}
)

print(response.json())

返回示例

{
  "id": "task_abc123",
  "status": "cancelled"
}

---

3. 注意事项与计费规则

1. 退费规则：
   • 处于排队中 (queued) 状态的任务，一经取消将百分之百全额返还/退回扣除的额度。
   • 处于生成中 (processing) 状态的任务，平台将尽最大可能尝试向底层渠道发送中断指令。若成功中断，则会根据底层实际产生消耗的部分计费并退还剩余额度；若底层任务由于已经接近完成而无法中断，则任务仍可能最终生成，该情况下不予退费。
   • 已经处于已完成 (completed/succeeded) 或 已失败 (failed) 状态的任务，无法被取消。
2. 幂等性： 取消接口通常是幂等的。对已经处于取消（cancelled）状态的任务重复发起取消请求，接口依然会返回成功。
3. 轮询机制： 建议取消操作完成后，客户端仍可通过状态查询接口验证任务状态，直至看到 "status": "cancelled"，以在 UI 界面上给予终端用户及时的中止反馈。