> ## 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.

# 使用 API 运行

> 使用你的 API 密钥、部署名称和变体，通过公共 API 调用提示词部署

# 使用 API 运行

当你想从自己的应用或服务调用提示词时，请使用公共调用端点。先在仪表板中创建提示词部署和变体，然后使用你的工作区 API 密钥调用该部署。

## 身份验证

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

有关如何创建和管理密钥，请参阅 [API 密钥](../workspace/api-keys)。

## 端点

`POST https://api.fetchhive.com/v1/prompt/invoke`

在调用此端点之前，请先从提示词编辑器创建或更新提示词部署。请参阅 [发布与版本管理](./publishing-and-versioning) 了解 UI 流程。

## 请求

使用以下请求结构：

| 字段           | 类型      | 必填 | 描述                                 |
| ------------ | ------- | -- | ---------------------------------- |
| `deployment` | string  | 是  | 你为该提示词创建的提示词部署名称                   |
| `variant`    | string  | 是  | 你想运行的提示词部署变体                       |
| `inputs`     | object  | 否  | 提示词使用的任何提示词变量的键值对                  |
| `streaming`  | boolean | 否  | 是否以流式方式返回响应                        |
| `metadata`   | object  | 否  | 调用方定义的扁平元数据，用于审计和日志过滤。不会作为提示词输入使用。 |

`metadata` 必须是扁平的且仅包含标量：字符串、数字、布尔值或 `null`。嵌套对象和数组会在运行启动之前返回验证错误。

此端点不接受顶层的 `image_urls` 或文档
`attachments`。如果已部署的提示词使用了图像 URL 消息部分，请在提示词编辑器中配置该图像 URL，或通过提示词内容中的 `inputs` 变量绑定它。对于运行时的图像/文档附件，请使用 [`POST /v1/agent/invoke`](../api-reference/agents/invoke) 调用智能体。

## 基本示例

```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
```

请将 `YOUR_API_KEY`、`YOUR_DEPLOYMENT_NAME`、`YOUR_VARIANT_NAME` 和 `inputs` 对象替换为你的真实值。

将 `metadata` 用于你希望在日志中查看或过滤的审计字段，例如客户 ID、套餐名称、地区或实验名称。不要把提示词变量放在那里；提示词变量应放在 `inputs` 中。请参阅 [调用元数据](../user-tracking/invoke-metadata) 获取示例和日志过滤详情。

## 响应

如果 `streaming` 为 `true`，则 API 会返回 `data:` 事件流，而不是一个最终的 JSON 对象。如果提供商在流打开后失败，API 会在关闭流之前发送一个最终的 `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"
}
```

最终用量事件：

```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`，API 返回单个 JSON 响应。提供商执行失败会返回 `502 Bad Gateway` 及 `error` 消息。例如：

```json theme={null}
{
  "request_id": "req_019d528660dd7e22b15e5b13a1931c50",
  "model": "gpt-5-nano-2025-08-07",
  "duration": 4.641960144042969,
  "reasoning": "**Clarifying summary request**\n\nI need to follow up on the user's request for a 50-word summary since their message was incomplete. I should ask them to clarify the text or topic they'd like summarized. I can suggest options like pasting a passage or specifying a source. I’ll also mention I can summarize up to 50 words or suggest a different length if they prefer. Let’s get that response ready!",
  "response": "I’m missing the text or topic to summarize. Please paste the passage (or name the work) you want summarized, and I’ll provide exactly 50 words. If you prefer a different length, tell me the target word count. I can summarize articles, chapters, speeches, or any provided content.",
  "usage": {
    "prompt_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0
    },
    "completion_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed"
}
```

## 后续步骤

* [发布与版本管理](./publishing-and-versioning)
* [使用 Python SDK 运行](./run-with-python-sdk) - 从 Python 调用提示词
* [使用 Node.js SDK 运行](./run-with-nodejs-sdk) - 从 Node.js 调用提示词
* [使用 Ruby SDK 运行](./run-with-ruby-sdk) - 从 Ruby 调用提示词
* [使用 PHP SDK 运行](./run-with-php-sdk) - 从 PHP 调用提示词