调用提示词

POST /v1/prompt/invoke 从你自己的应用或服务运行提示词部署。

身份验证

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

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。有效示例：

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

无效示例：

{
  "metadata": {
    "customer": {
      "id": "cus_123"
    },
    "tags": ["enterprise"]
  }
}

响应

如果 streaming 为 true，Fetch Hive 返回事件流。如果在流打开后提供商失败,Fetch Hive 会在关闭流前发送一个最终的 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"
}

最终 usage 事件示例：

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "usage",
  "usage": {
    "duration": 4.79230260848999,
    "prompt_tokens": {
      "total_tokens": 24,
      "cached_tokens": 0,
      "cached_read_tokens": 0,
      "cache_write_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
}

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

{
  "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,
      "cached_read_tokens": 0,
      "cache_write_tokens": 0
    },
    "completion_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed"
}

示例

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。

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 来表示终态和关联。

Fetch Hive API

REST API

Invoke

调用提示词

身份验证

请求体

响应

示例

Webhook 触发器

相关内容

​调用提示词

​身份验证

​请求体

​响应

​示例

​Webhook 触发器

​相关内容

调用提示词

身份验证

请求体

响应

示例

Webhook 触发器

相关内容