跳转到主要内容

使用 API 运行

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

身份验证

Authorization: Bearer YOUR_API_KEY
有关如何创建和管理密钥,请参阅 API 密钥

端点

POST https://api.fetchhive.com/v1/prompt/invoke 在调用此端点之前,请先从提示词编辑器创建或更新提示词部署。请参阅 发布与版本管理 了解 UI 流程。

请求

使用以下请求结构:
字段类型必填描述
deploymentstring你为该提示词创建的提示词部署名称
variantstring你想运行的提示词部署变体
inputsobject提示词使用的任何提示词变量的键值对
streamingboolean是否以流式方式返回响应
metadataobject调用方定义的扁平元数据,用于审计和日志过滤。不会作为提示词输入使用。
metadata 必须是扁平的且仅包含标量:字符串、数字、布尔值或 null。嵌套对象和数组会在运行启动之前返回验证错误。 此端点不接受顶层的 image_urls 或文档 attachments。如果已部署的提示词使用了图像 URL 消息部分,请在提示词编辑器中配置该图像 URL,或通过提示词内容中的 inputs 变量绑定它。对于运行时的图像/文档附件,请使用 POST /v1/agent/invoke 调用智能体。

基本示例

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_KEYYOUR_DEPLOYMENT_NAMEYOUR_VARIANT_NAMEinputs 对象替换为你的真实值。 metadata 用于你希望在日志中查看或过滤的审计字段,例如客户 ID、套餐名称、地区或实验名称。不要把提示词变量放在那里;提示词变量应放在 inputs 中。请参阅 调用元数据 获取示例和日志过滤详情。

响应

如果 streamingtrue,则 API 会返回 data: 事件流,而不是一个最终的 JSON 对象。如果提供商在流打开后失败,API 会在关闭流之前发送一个最终的 error 事件。

流式响应

你可以在流期间接收不同类型的事件。例如: 推理或思考事件:
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "reasoning",
  "model": "gpt-5-nano",
  "response": " seems"
}
响应事件:
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "response",
  "model": "gpt-5-nano",
  "response": " too"
}
最终用量事件:
{
  "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"
}
错误事件:
{
  "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
}

非流式响应

如果 streamingfalse,API 返回单个 JSON 响应。提供商执行失败会返回 502 Bad Gatewayerror 消息。例如:
{
  "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"
}

后续步骤