API 接口文档 - 意刻·imoment

概述

意刻 API 允许开发者通过 RESTful 接口访问平台的搜索和问答能力。所有 API 请求均需通过 HTTPS 发送至 https://imoment.top。

认证

所有 API 端点均需通过 API Key 认证。在请求头中传递您的密钥：

x-api-key: imoment_xxx

前往仪表盘 → API 密钥页面创建和管理密钥。

端点

方法	端点	说明	计费
`GET`	`/api/v1/query`	全文搜索问题	免费
`POST`	`/api/v1/question`	获取问题详情与 AI 解答	扣 10 积分
`GET`	`/api/v1/balance`	查询积分余额	免费

GET /api/v1/query

全文搜索问题，返回匹配的问题列表（最多 20 条）。

请求

GET /api/v1/query?q=光合作用 HTTP/1.1
Host: imoment.top
x-api-key: imoment_xxx

参数	位置	类型	必填	说明
`q`	query	string	是	搜索关键词（也可用 `search`）

响应

{
  "data": [
    {
      "uuid": "abc123...",
      "question_type": "single_choice",
      "title": "光合作用的主要场所是？",
      "options": { "A": "线粒体", "B": "叶绿体", "C": "细胞核", "D": "内质网" },
      "has_answer": true,
      "has_ai_interpretation": true
    }
  ],
  "meta": {
    "apiKeyId": "key_xxx",
    "charged": false
  }
}

字段	类型	说明
`data[].uuid`	string	问题唯一标识
`data[].question_type`	string	题型枚举
`data[].title`	string	问题标题
`data[].options`	object	选项键值对（可为 null）
`data[].has_answer`	boolean	是否有正确答案
`data[].has_ai_interpretation`	boolean	是否有 AI 解读

题型枚举

值	说明
`single_choice`	单选题
`multiple_choice`	多选题
`true_false`	判断题
`fill_blank`	填空题
`short_answer`	简答题
`essay`	论述题
`other`	其他

示例（Node.js SDK）

import { Imoment } from "@imoment/sdk";
const client = new Imoment({ apiKey: "imoment_xxx" });

const { data } = await client.query("光合作用");
for (const q of data) {
  console.log(`${q.title} (${q.question_type})`);
}

POST /api/v1/question

获取问题详情与 AI 解答（扣 10 积分）。返回完整题目信息、正确答案、解析以及多模型 AI 解读。

请求

POST /api/v1/question HTTP/1.1
Host: imoment.top
x-api-key: imoment_xxx
Content-Type: application/json

{
  "id": "abc123..."
}

参数	位置	类型	必填	说明
`id`	body	string	是	问题 UUID（也可用 `questionId`）

响应

{
  "data": {
    "question": {
      "uuid": "abc123...",
      "question_type": "single_choice",
      "title": "光合作用的主要场所是？",
      "options": { "A": "线粒体", "B": "叶绿体", "C": "细胞核", "D": "内质网" },
      "updated_at": "2026-01-01T00:00:00Z",
      "has_ai_interpretation": true
    },
    "solution": {
      "correct_answer": "B",
      "explanation": "光合作用在叶绿体中进行，叶绿体含有叶绿素...",
      "interpretations": [
        {
          "uuid": "interp_xxx",
          "interpretation": "本题考查光合作用的基础知识...",
          "model": "deepseek-v4",
          "created_at": "2026-01-01T00:00:00Z"
        }
      ]
    }
  },
  "meta": {
    "charged": true,
    "chargedPoints": 10,
    "balance": 990,
    "ledgerId": "ledger_xxx"
  }
}

字段	类型	说明
`data.question`	object	完整题目信息
`data.question.options`	object	选项键值对（可为 null）
`data.solution.correct_answer`	string	正确答案
`data.solution.explanation`	string	官方解析（可为 null）
`data.solution.interpretations`	array	AI 多模型解读列表
`data.solution.interpretations[].model`	string	生成解读的 AI 模型
`data.solution.interpretations[].interpretation`	string	AI 解读内容
`meta.chargedPoints`	number	本次扣减积分
`meta.balance`	number	扣减后余额

错误码

HTTP 状态码	code	说明
400	`missing_question_id`	缺少问题 ID
404	`question_not_found`	问题未找到
402	`insufficient_balance`	积分不足

示例（Node.js SDK）

const { data } = await client.getQuestion("abc123...");
console.log(data.question.title);
console.log(data.solution.correct_answer);
for (const interp of data.solution.interpretations) {
  console.log(`[${interp.model}] ${interp.interpretation}`);
}
console.log(`扣减后余额: ${data.meta.balance}`);

GET /api/v1/balance

查询当前 API Key 的积分余额。

请求

GET /api/v1/balance HTTP/1.1
Host: imoment.top
x-api-key: imoment_xxx

响应

{
  "data": {
    "balance": 990
  }
}

示例（Node.js SDK）

const { data } = await client.getBalance();
console.log(`当前余额: ${data.balance}`);

错误处理

所有错误响应均遵循统一格式：

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key"
  }
}

HTTP 状态码	code	说明
401	`missing_api_key`	缺少 API Key
401	`invalid_api_key`	API Key 无效
403	`user_banned`	用户已被封禁
402	`insufficient_balance`	积分不足
429	`rate_limited`	请求频率超限

错误处理示例

import { Imoment, ImomentApiError } from "@imoment/sdk";

try {
  await client.getQuestion("bad-id");
} catch (err) {
  if (err instanceof ImomentApiError) {
    console.error(`${err.code} (HTTP ${err.status}): ${err.message}`);
  }
}

多语言 SDK

我们提供以下语言的官方 SDK，API 调用方式及各语言示例详见各 SDK 目录：

语言	目录	包管理器
Node.js / TypeScript	`sdk/nodejs`	npm / pnpm / yarn
Python	`sdk/python`	pip / poetry
PHP	`sdk/php`	composer
Go	`sdk/go`	go get
Rust	`sdk/rust`	cargo

所有 SDK 包名统一为 imoment，提供 query、getQuestion、getBalance 三个核心方法。

计费说明

端点	积分消耗	说明
`GET /api/v1/query`	0	免费搜索
`POST /api/v1/question`	10	每次获取详情 + AI 解答
`GET /api/v1/balance`	0	免费查询

积分可通过仪表盘充值获取。余额不足时 /question 接口将返回 insufficient_balance 错误。