Saltar al contenido principal

​
Ejecutar con API

Usa el endpoint público de invocación cuando quieras llamar a un prompt desde tu propia aplicación o servicio. Primero crea un deployment de prompt y una variante en el dashboard, luego invoca el deployment con tu clave de API del workspace.

​
Autenticación

Authorization: Bearer YOUR_API_KEY
Consulta API Keys para saber cómo crear y administrar claves.

​
Endpoint

POST https://api.fetchhive.com/v1/prompt/invoke Antes de llamar a este endpoint, crea o actualiza un deployment de prompt desde el editor de prompts. Consulta Publicación y versionado para el flujo de la interfaz.

​
Solicitud

Usa esta forma de solicitud:
CampoTipoRequeridoDescripción
deploymentstringSíEl nombre del deployment de prompt que creaste para el prompt
variantstringSíLa variante del deployment de prompt que quieres ejecutar
inputsobjectNoPares clave-valor para cualquier variable de prompt utilizada por el prompt
streamingbooleanNoSi la respuesta debe transmitirse
metadataobjectNoMetadata plana definida por quien llama, para auditoría y filtrado de registros. No se usa como entrada del prompt.
metadata debe ser plana y solo escalar: cadenas, números, booleanos o null. Los objetos anidados y los arreglos devuelven un error de validación antes de que comience la ejecución. Este endpoint no acepta image_urls ni attachments de documento a nivel superior. Si un prompt desplegado usa una parte de mensaje con URL de imagen, configura esa URL de imagen en el editor de prompts o vincúlala mediante una variable inputs en el contenido del prompt. Para adjuntos de imagen/documento en tiempo de ejecución, invoca un agente con POST /v1/agent/invoke.

​
Ejemplo básico

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
Reemplaza YOUR_API_KEY, YOUR_DEPLOYMENT_NAME, YOUR_VARIANT_NAME y el objeto inputs con tus valores reales. Usa metadata para campos de auditoría que quieras ver o filtrar en los registros, como IDs de clientes, nombres de planes, regiones o nombres de experimentos. No pongas variables de prompt ahí; las variables de prompt van en inputs. Consulta Metadata de invoke para ver ejemplos y detalles de filtrado de registros.

​
Respuesta

Si streaming es true, la API devuelve una transmisión de eventos data: en lugar de un solo objeto JSON final. Si el proveedor falla después de que la transmisión se ha abierto, la API envía un evento error final antes de cerrar la transmisión.

​
Respuesta en streaming

Puedes recibir diferentes tipos de eventos durante la transmisión. Por ejemplo: Evento de razonamiento o pensamiento: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "reasoning",
  "model": "gpt-5-nano",
  "response": " seems"
}
Evento de respuesta: 
{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "type": "response",
  "model": "gpt-5-nano",
  "response": " too"
}
Evento final de uso: 
{
  "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: 
{
  "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
}

​
Respuesta sin streaming

Si streaming es false, la API devuelve una sola respuesta JSON. Los fallos de ejecución del proveedor devuelven 502 Bad Gateway con un mensaje de error. Por ejemplo: 
{
  "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"
}

​
Siguientes pasos