快速入门指南

要使用 Discuse 审核内容，请向 https://api.discuse.com/api/v2/check 发送一个 POST 请求，并带上 X-API-Key 请求头和一个 JSON 请求体，其中包含你想检查的文本、图片 URL 或文件 URL。响应会返回按类别细分的结果，以及一个统一的 has_violations 标志。本指南将带你完成第一次调用、了解响应格式，并掌握基本的错误处理——全程大约五分钟。

前提条件

开始之前，请确保你已经具备：

一个 Discuse 账户（在 discuse.com 注册）
从控制台获取的 API 密钥
一个用于发送 HTTP 请求的工具（cURL、Postman，或你的应用程序代码）

第 1 步：获取你的 API 密钥

注册后，进入控制台并找到 API Keys 部分。点击“Create New Key”生成新的 API 密钥。请妥善保管此密钥——它可用于访问你的账户并消耗你的使用配额。

每个 Discuse 密钥都以 disc_ 前缀开头，例如：

disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345-_6789

第 2 步：发起你的第一次 API 调用

测试 API 最简单的方式是发送文本分析请求。下面是一个使用 cURL 的基础示例：

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": {
      "text": "Hello, this is a test message to analyze!"
    }
  }'

第 3 步：理解响应

成功的请求会返回一个包含分析结果的 JSON 响应：

{
  "has_violations": false,
  "cached": false,
  "results": {
    "hits": false,
    "sentiment": {
      "is_negative": false,
      "is_toxic": false,
      "score": 0.03,
      "toxic": 0.02,
      "profanity": 0.01,
      "threat": 0.00,
      "insult": 0.03,
      "hit": false
    },
    "spamfinder": {
      "label": "ham",
      "confidence": 0.08,
      "is_spam": false,
      "hit": false
    },
    "language": {
      "language": "en",
      "confidence": 0.98
    }
  },
  "usage": {
    "api_requests_used": 42,
    "api_requests_limit": 1000,
    "api_requests_remaining": 958
  }
}

只有在项目设置中启用计时时，才会包含 processing_time_ms；而 message 只会在配额超限响应中设置——因此上面的示例省略了这两个字段。

响应字段说明

字段	说明
`has_violations`	布尔值：如果任何已启用的检查标记了该内容，则为 `true`（与 `results.hits` 一致）
`cached`	表示该结果是否来自缓存（仍会按一次请求计入配额）
`results.hits`	所有检查的总体命中标志
`results.sentiment`	毒性评分，范围从 0.0（安全）到 1.0（高毒性），并包含 `is_toxic`/`hit` 判定标志
`results.spamfinder`	垃圾内容判定：`label`、`confidence`、`is_spam`（原始结果）和 `hit`（考虑阈值后的结果）
`results.language`	检测到的 `language` 代码和 `confidence`
`usage`	当前计费周期内你的 API 请求用量、上限和剩余配额

第 4 步：分析图片

要检查图片是否包含 NSFW 内容，请在请求中加入图片 URL：

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "content": {
      "image_urls": ["https://example.com/image.jpg"]
    },
    "settings": {
      "check_images": true
    }
  }'

第 5 步：组合多项检查

你可以在一次请求中同时分析文本和图片：

{
  "content": {
    "text": "Check out this amazing photo!",
    "image_urls": ["https://example.com/photo.jpg"]
  },
  "settings": {
    "check_sentiment": true,
    "check_spam": true,
    "check_images": true,
    "check_language": true
  }
}

集成示例

JavaScript/Node.js

async function checkContent(text) {
  const response = await fetch('https://api.discuse.com/api/v2/check', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.DISCUSE_API_KEY
    },
    body: JSON.stringify({
      content: { text }
    })
  });

  return response.json();
}

// Usage
const result = await checkContent('Hello world!');
if (result.has_violations) {
  console.log('Content flagged:', result.message);
}

Python

import requests
import os

def check_content(text):
    response = requests.post(
        'https://api.discuse.com/api/v2/check',
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': os.environ['DISCUSE_API_KEY']
        },
        json={
            'content': {'text': text}
        }
    )
    return response.json()

# Usage
result = check_content('Hello world!')
if result['has_violations']:
    print(f"Content flagged: {result['message']}")

缓存会计入我的配额吗？

Discuse 会将相同内容的结果缓存几分钟。当响应中包含 "cached": true 时，说明结果来自缓存，因此返回速度更快，也不会重新运行检查。该请求仍会按一次 API 请求计入你的配额，但底层按功能计费的扫描（图片、杀毒）不会重复计费。缓存主要适用于同一内容在短时间内被反复提交的场景。

我该如何处理错误？

成功的检查会返回 HTTP 200。密钥无效、触发速率限制或请求格式错误会返回非 2xx 状态。请注意，配额耗尽并不是 HTTP 错误：当你的计费周期配额用完时，API 仍会返回 200，并带有 has_violations: false 和说明配额已超出的 message——请检查 message 和 usage 字段，而不是仅依赖状态码。

try {
  const response = await fetch('https://api.discuse.com/api/v2/check', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': apiKey
    },
    body: JSON.stringify({ content: { text } })
  });

  if (!response.ok) {
    if (response.status === 401 || response.status === 403) {
      throw new Error('Invalid or unauthorized API key');
    } else if (response.status === 429) {
      throw new Error('Rate limit exceeded - slow down requests');
    }
    throw new Error(`API error: ${response.status}`);
  }

  const result = await response.json();

  // Quota exhaustion is returned as a 200 with a message, not an error status.
  if (result.message && result.usage && result.usage.api_requests_remaining === 0) {
    console.warn('Quota exceeded:', result.message);
  }

  return result;
} catch (error) {
  console.error('Content check failed:', error);
  throw error;
}

后续步骤

现在你已经完成了第一次 API 调用，可以继续探索以下资源：

身份验证与 API 密钥 - 了解安全的密钥管理
文本分析 - 深入了解情感分析和垃圾内容检测
图片 NSFW 检测 - 保护你的平台免受不当图片影响
配置阈值 - 微调检测灵敏度