# 获取 AI 答案

`POST https://api.dataforgeo.dev/v1/geo/answer` · all plans

拿一个 prompt 在多个引擎上的 AI 答案，并标出品牌提及、引用来源和竞品实体。所有档位可用。

### 参数

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `prompt` | string | 是 | 要问的问题，最长 2,000 字符 |
| `engines` | string[] | 是 | 引擎 id 列表，见「引擎与地区」 |
| `brand` | string | 否 | 要识别的品牌名；不传则只返回答案和实体 |
| `brand_variants` | string[] | 否 | 品牌别名，例如片假名、英文名 |
| `competitors` | string[] | 否 | 竞品名，最多 20 个 |
| `location` | string | 否 | 国家代码，默认 US |
| `language` | string | 否 | 语言代码，默认按 location 推断 |
| `samples` | integer | 否 | 每个引擎采样次数，1–10，默认 1 |
| `fresh` | boolean | 否 | true 时跳过缓存，默认 false |
| `async` | boolean | 否 | true 时立即返回 job_id，见「异步任务与账户」 |
| `webhook_url` | string | 否 | 异步完成后回调的地址 |

### 请求示例

```bash
curl https://api.dataforgeo.dev/v1/geo/answer \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "prompt": "东京有哪些适合家庭入住的民宿？",
    "engines": [
      "chatgpt"
    ],
    "brand": "晓宅",
    "location": "JP",
    "language": "zh-CN"
  }'
```

### 响应示例

```json
{
  "request_id": "req_8f2c1a",
  "prompt": "东京有哪些适合家庭入住的民宿？",
  "credits_used": 1,
  "answers": [
    {
      "engine": "chatgpt",
      "sample": 1,
      "status": "ok",
      "cached": false,
      "generated_at": "2026-11-02T00:31:12Z",
      "text": "……",
      "brand": {
        "mentioned": true,
        "mention_count": 2,
        "first_position": 3,
        "sentiment": "positive"
      },
      "entities": [
        {
          "name": "晓宅",
          "type": "brand",
          "position": 3,
          "is_competitor": false
        },
        {
          "name": "Example Stay",
          "type": "brand",
          "position": 1,
          "is_competitor": true
        }
      ],
      "citations": [
        {
          "url": "https://example.com/guide",
          "domain": "example.com",
          "position": 1,
          "is_brand_domain": false
        }
      ]
    }
  ]
}
```

- status 取值：ok、no_answer、timeout、failed；后三种不扣费。
- status 为 timeout 或 failed 时，答案多一个 error 字段说明原因，取值见下表；ok 和 no_answer 的答案没有这个字段。
- first_position 是品牌在答案推荐列表中第一次出现的位次，未出现时为 null。

### 答案的 error 字段

| error | 含义 |
| --- | --- |
| `upstream_timeout` | 引擎在时限内没有给出答案（已自动重试） |
| `upstream_error` | 引擎返回错误，自动重试后仍失败 |
| `engine_unavailable` | 该引擎暂时不可用，没有发出调用；可在 /v1/status 查看状态 |

### 失败的答案示例

```json
{
  "engine": "grok",
  "sample": 1,
  "status": "failed",
  "error": "engine_unavailable",
  "cached": false
}
```