Invocar flujo de trabajo

POST /v1/workflow/invoke Ejecuta un despliegue de flujo de trabajo 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 Workflows, luego Deployments, abre la variante del despliegue que deseas ejecutar y haz clic en Code Snippet para copiar la forma actual de la solicitud desde Fetch Hive.

Campo	Tipo	Requerido	Descripción
`deployment`	string	Sí	El nombre del despliegue del flujo de trabajo
`variant`	string	Sí	El nombre de la variante del despliegue
`inputs`	object	No	Pares clave-valor para las variables definidas en el paso Start
`async`	object	No	Ajustes de entrega por callback
`metadata`	object	No	Metadatos planos definidos por el llamador para auditoría y filtrado de registros. Esto no se usa como entrada del flujo de trabajo.

Los valores de inputs se validan contra las definiciones de entrada del paso Start del flujo de trabajo antes de iniciar la ejecución. Las entradas de inicio de tipo arreglo deben ser arreglos JSON nativos, no cadenas JSON. 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. 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"]
  }
}

Si incluyes async, usa estos campos anidados:

Campo	Tipo	Requerido	Descripción
`async.enabled`	boolean	Sí	Establece en `true` para devolver inmediatamente
`async.callback_url`	string	Sí cuando la entrega por callback está habilitada	La URL de callback que Fetch Hive debe llamar cuando termine la ejecución

Si activas Callback delivery en el diálogo de fragmento de código, Fetch Hive también muestra un Signing secret para la verificación del callback.

Respuesta

Cuando la entrega por callback está desactivada, Fetch Hive espera a que termine el flujo de trabajo y devuelve la salida en una sola respuesta.

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "completed",
  "output": "State of enterprise AI in 2026: enterprises are moving from experimentation to operational systems with stricter evaluation, governance, and tooling requirements."
}

output depende de la forma según el tipo de resultado del flujo de trabajo. Para salidas finales de generación de imágenes, output es un objeto con settings y assets:

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "completed",
  "output": {
    "settings": {
      "model": "grok-imagine-image-quality",
      "provider": "xai",
      "image_count": 1
    },
    "assets": [
      {
        "id": "asset_1",
        "file_url": "https://uploads.fetchhive.com/...png",
        "file_name": "step_3_123456789_1.png",
        "file_size": 505042,
        "file_type": "image/png"
      }
    ]
  }
}

Cuando async.enabled es true, Fetch Hive devuelve inmediatamente.

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "running",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}

Con alta concurrencia, Fetch Hive también puede devolver un estado de entrega por callback encolada.

{
  "request_id": "req_019d52846ea37682b03522fd0695cc43",
  "run_status": "queued",
  "webhook_secret": "YOUR_WEBHOOK_SECRET"
}

Ejemplo

Solicitud directa

curl 'https://api.fetchhive.com/v1/workflow/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": {
      "topic": "State of enterprise AI in 2026"
    },
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise"
    }
  }' \
  --compressed

Solicitud con entrega por callback

curl 'https://api.fetchhive.com/v1/workflow/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",
    "async": {
      "enabled": true,
      "callback_url": "https://example.com/callback"
    },
    "inputs": {
      "topic": "State of enterprise AI in 2026"
    }
  }' \
  --compressed

Relacionado

Consulta Autenticación para configurar la clave de API
Consulta Entrega por callback y disparadores webhook para la entrega por callback y la verificación de firmas
Consulta Ejecutar con API para una guía centrada en flujos de trabajo

Fetch Hive API

REST API

Invoke

Invocar flujo de trabajo

Autenticación

Cuerpo de la solicitud

Respuesta

Ejemplo

Solicitud directa

Solicitud con entrega por callback

Relacionado

​Invocar flujo de trabajo

​Autenticación

​Cuerpo de la solicitud

​Respuesta

​Ejemplo

​Solicitud directa

​Solicitud con entrega por callback

​Relacionado

Invocar flujo de trabajo

Autenticación

Cuerpo de la solicitud

Respuesta

Ejemplo

Solicitud directa

Solicitud con entrega por callback

Relacionado