Saltar al contenido principal

​
Invocar prompt

POST /v1/prompt/invoke Ejecuta un despliegue de prompt desde tu propia app o servicio.

​
Autenticación

Envía tu clave de API del espacio de trabajo en el encabezado Authorization. 
Authorization: Bearer YOUR_API_KEY

​
Cuerpo de la solicitud

Abre Prompts, luego Deployments, abre la variante del despliegue que deseas ejecutar y haz clic en Code Snippet para ver esta forma de la solicitud en Fetch Hive.
CampoTipoRequeridoDescripción
deploymentstringSíEl nombre del despliegue del prompt
variantstringSíEl nombre de la variante del despliegue
inputsobjectNoPares clave-valor para las variables del prompt
streamingbooleanNoTransmite eventos de respuesta en lugar de esperar una única respuesta JSON final
metadataobjectNoMetadatos planos definidos por el llamador para auditoría y filtrado de registros. Esto no se usa como entrada del prompt.
metadata debe ser un objeto plano. Las claves deben ser cadenas no vacías y los valores deben ser cadenas, números, booleanos o null. Los arreglos y objetos anidados se rechazan antes de iniciar la ejecución. POST /v1/prompt/invoke no acepta image_urls ni attachments de documentos a nivel superior. Si un prompt desplegado usa una parte de mensaje con URL de imagen, configura esa URL de imagen en el editor del prompt o enlázala mediante una variable de inputs en el contenido del prompt. Para adjuntos de imagen/documento en runtime, usa POST /v1/agent/invoke. Válido: 
{
  "metadata": {
    "customer_id": "cus_123",
    "plan": "enterprise",
    "trial": false,
    "invoice_count": 12,
    "region": null
  }
}
Inválido: 
{
  "metadata": {
    "customer": {
      "id": "cus_123"
    },
    "tags": ["enterprise"]
  }
}

​
Respuesta

Si streaming es true, Fetch Hive devuelve un flujo de eventos. Si el proveedor falla después de que se haya abierto el flujo, Fetch Hive envía un evento error final antes de cerrar el flujo. Evento de razonamiento de ejemplo: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "reasoning",
  "model": "gpt-5-nano",
  "response": " seems"
}
Evento de respuesta de ejemplo: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "response",
  "model": "gpt-5-nano",
  "response": " too"
}
Evento final de uso de ejemplo: 
{
  "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"
}
Evento de error de ejemplo: 
{
  "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
}
Si streaming es false, Fetch Hive devuelve una sola respuesta JSON. Los fallos de ejecución del proveedor devuelven 502 Bad Gateway con un mensaje 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
    },
    "completion_tokens": {
      "total_tokens": 187,
      "reasoning_tokens": 64
    },
    "total_tokens": 211
  },
  "stop_reason": "completed"
}

​
Ejemplo

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

​
Disparador webhook

POST /v1/prompt/webhooks/{prompt_endpoint_id}/variants/{variant_id} Usa un disparador webhook de prompt cuando un servicio externo deba iniciar una variante de prompt desplegada sin una clave de API del espacio de trabajo. La solicitud debe incluir el secreto webhook del endpoint del prompt en X-Fetch-Hive-Webhook-Secret. Si una herramienta de terceros no puede establecer encabezados personalizados, usa ?secret=YOUR_WEBHOOK_SECRET como alternativa. Los disparadores webhook de prompt siempre usan entrega por callback. Incluye async.callback_url; Fetch Hive devuelve 202 con request_id y run_status: "running", y luego entrega prompt.completed o prompt.failed a la URL de callback. 
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 debe ser un objeto. Cada variable declarada en la versión del prompt desplegado seleccionada debe estar presente, pero los valores pueden ser cadenas vacías o null cuando deseas intencionalmente un render en blanco. Se permiten claves de entrada adicionales. metadata sigue la misma regla plana de solo escalares que las invocaciones normales de prompt y aparece en el filtrado de registros. Fetch Hive firma el callback saliente con el mismo secreto webhook usado para la autenticación del disparador entrante. El data del callback contiene response en prompt.completed y error en prompt.failed; usa el event_type y el request_id de nivel superior para el estado terminal y la correlación.

​
Relacionado

  • Consulta Autenticación para configurar la clave de API
  • Consulta Prompts para el editor de prompts y el contexto de despliegue
  • Consulta Ejecutar con API para una guía centrada en el prompt