> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoke

> 使用部署名称和变体,通过公开的 Fetch Hive API 运行提示词部署

# 调用提示词

`POST /v1/prompt/invoke`

从你自己的应用或服务运行提示词部署。

## 身份验证

在 `Authorization` 请求头中发送工作区 API 密钥。

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## 请求体

打开 **Prompts**，然后 **Deployments**，打开你想运行的部署变体,并点击 **Code Snippet** 即可在 Fetch Hive 中查看此请求结构。

| 字段           | 类型      | 是否必填 | 描述                               |
| ------------ | ------- | ---- | -------------------------------- |
| `deployment` | string  | 是    | 提示词部署名称                          |
| `variant`    | string  | 是    | 部署变体名称                           |
| `inputs`     | object  | 否    | 提示词变量的键值对                        |
| `streaming`  | boolean | 否    | 流式传输响应事件,而不是等待一条最终的 JSON 响应      |
| `metadata`   | object  | 否    | 调用方定义的扁平元数据,用于审计和日志筛选。不会用作提示词输入。 |

`metadata` 必须是扁平对象。键必须是非空字符串,值必须是字符串、数字、布尔值或 `null`。数组和嵌套对象会在运行启动前被拒绝。

`POST /v1/prompt/invoke` 不接受顶层的 `image_urls` 或文档 `attachments`。如果已部署的提示词使用了图片 URL 消息组件,请在提示词编辑器中配置该图片 URL,或在提示词内容中通过 `inputs` 变量绑定它。对于运行时的图片/文档附件,请使用 [`POST /v1/agent/invoke`](../agents/invoke)。

有效示例：

```json theme={null}
{
  "metadata": {
    "customer_id": "cus_123",
    "plan": "enterprise",
    "trial": false,
    "invoice_count": 12,
    "region": null
  }
}
```

无效示例：

```json theme={null}
{
  "metadata": {
    "customer": {
      "id": "cus_123"
    },
    "tags": ["enterprise"]
  }
}
```

## 响应

如果 `streaming` 为 `true`，Fetch Hive 返回事件流。如果在流打开后提供商失败,Fetch Hive 会在关闭流前发送一个最终的 `error` 事件。

推理事件示例：

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "reasoning",
  "model": "gpt-5-nano",
  "response": " seems"
}
```

响应事件示例：

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "response",
  "model": "gpt-5-nano",
  "response": " too"
}
```

最终 usage 事件示例：

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "usage",
  "usage": {
    "duration": 4.79230260848999,
    "prompt_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "completion_tokens": {
      "total_tokens": 170,
      "reasoning_tokens": 64
    },
    "total_tokens": 194
  },
  "stop_reason": "completed"
}
```

错误事件示例：

```json theme={null}
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "error",
  "error": "cohere provider stream error: HTTP 400: invalid request",
  "message": "cohere provider stream error: HTTP 400: invalid request",
  "provider": "cohere",
  "error_type": "provider_stream_error",
  "status_code": 502
}
```

如果 `streaming` 为 `false`，Fetch Hive 返回一条 JSON 响应。提供商执行失败时返回 `502 Bad Gateway`，带有 `error` 消息。

```json theme={null}
{
  "request_id": "req_019d528660dd7e22b15e5b13a1931c50",
  "model": "gpt-5-nano-2025-08-07",
  "duration": 4.641960144042969,
  "reasoning": "The request asks for a short summary.",
  "response": "Fetch Hive helps teams ship AI products faster.",
  "usage": {
    "prompt_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "completion_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed"
}
```

## 示例

```bash theme={null}
curl 'https://api.fetchhive.com/v1/prompt/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
    "deployment": "YOUR_DEPLOYMENT_NAME",
    "variant": "YOUR_VARIANT_NAME",
    "inputs": {
      "text": "Fetch Hive helps teams ship AI products faster."
    },
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    },
    "streaming": true
  }' \
  --compressed
```

## Webhook 触发器

`POST /v1/prompt/webhooks/{prompt_endpoint_id}/variants/{variant_id}`

当外部服务需要在不使用工作区 API 密钥的情况下启动已部署的提示词变体时,使用提示词 webhook 触发器。请求必须在 `X-Fetch-Hive-Webhook-Secret` 中包含提示词端点 webhook 密钥。如果第三方工具无法设置自定义请求头,可以退而使用 `?secret=YOUR_WEBHOOK_SECRET`。

webhook 提示词触发器始终使用回调投递。包含 `async.callback_url`；Fetch Hive 返回 `202`，带有 `request_id` 和 `run_status: "running"`，随后向回调 URL 投递 `prompt.completed` 或 `prompt.failed`。

```bash theme={null}
curl 'https://api.fetchhive.com/v1/prompt/webhooks/YOUR_PROMPT_ENDPOINT_ID/variants/YOUR_VARIANT_ID' \
  -H 'X-Fetch-Hive-Webhook-Secret: YOUR_WEBHOOK_SECRET' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "inputs": {
      "text": "Fetch Hive helps teams ship AI products faster."
    },
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    },
    "user": "external-user-1",
    "async": {
      "callback_url": "https://example.com/callback"
    }
  }'
```

`inputs` 必须是对象。所选已部署提示词版本声明的每个变量都必须存在,但当你有意要渲染空白时,值可以是空字符串或 `null`。允许多余的输入键。`metadata` 遵循与普通提示词调用相同的扁平且仅含标量的规则,并会出现在日志筛选中。

Fetch Hive 使用与入站触发器认证相同的 webhook 密钥对出站回调进行签名。
回调 `data` 在 `prompt.completed` 时包含 `response`,在 `prompt.failed` 时包含 `error`；使用顶层的 `event_type` 和 `request_id` 来表示终态和关联。

## 相关内容

* 请参阅[身份验证](./authentication)了解 API 密钥设置
* 请参阅[提示词](../prompts/overview)了解提示词编辑器和部署上下文
* 请参阅[通过 API 运行](../prompts/run-with-api)获取面向提示词的指南