--- title: Inicio rápido | RunAPI description: Cree una Tarea asíncrona y gestione el sondeo, la finalización, los fallos y las devoluciones de llamada. url: https://runapi.ai/es/docs/guides/task-api/quickstart.md canonical: https://runapi.ai/es/docs/guides/task-api/quickstart locale: es --- > Versión HTML: https://runapi.ai/es/docs/guides/task-api/quickstart > Índice del sitio para agentes: https://runapi.ai/llms.txt # Inicio rápido RunAPI usa Tasks para la generación asíncrona de imágenes, vídeo, audio y música. Una solicitud de creación responde rápidamente; la aplicación luego sondea la Task o recibe los eventos de devolución de llamada indicados en la Referencia de la API de ese endpoint. ## Crear una Tarea Elija un modelo y un endpoint en el Catálogo y envíe las entradas requeridas por el endpoint. Este ejemplo inicia una Tarea de texto a imagen con Flux 2: ```shell curl -X POST "https://runapi.ai/api/v1/flux_2/text_to_image" \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Idempotency-Key: 8c8ba3c9-0ce0-4bbd-a9a7-bf59ab639286" \ -H "Content-Type: application/json" \ -d '{ "model": "flux-2-pro-text-to-image", "prompt": "A product photograph on a clean studio background" }' ``` Una solicitud asíncrona aceptada devuelve `202 Accepted` con un identificador de tarea: ```json { "id": "task_id", "status": "processing" } ``` Guarde `id` junto con el registro de su aplicación. Es el identificador estable que se usa para el sondeo, el soporte y la reconciliación de devoluciones de llamada. ## Evitar la creación de tareas duplicadas Los endpoints de creación de tareas aceptan un encabezado opcional `Idempotency-Key` con un valor opaco de hasta 512 caracteres. Genera un valor por cada tarea lógica y consérvalo con la solicitud hasta saber si fue aceptada. Si un tiempo de espera o un fallo de conexión deja el resultado desconocido, reintente la misma solicitud de creación de Task con la misma clave. RunAPI devuelve el Task original en lugar de crear y cobrar por uno nuevo. Reutilizar una clave con una solicitud de creación de Task diferente devuelve `409 Conflict`. Genere una nueva clave para un Task intencionalmente nuevo y no use `X-Client-Request-Id` como esta clave. ## Recuperar una solicitud síncrona interrumpida Los endpoints síncronos lentos normalmente mantienen la conexión abierta y devuelven la misma respuesta terminal que antes. No se requieren cambios de sondeo para las integraciones existentes. Para un presupuesto de conexión intencionalmente más corto, envíe `Prefer: wait=N`. Si la tarea aún está en ejecución después de ese presupuesto explícito, RunAPI devuelve `202 Accepted` con el mismo `id` de tarea, una URL opaca `Location` para recuperación y `Retry-After` con el retraso de consulta sugerido. Siga `Location` exactamente en lugar de construir una URL de resultado. Un resultado de tarea completada preserva el estado HTTP terminal, los encabezados permitidos, el tipo de contenido y el cuerpo; decodifique `response.body` según `response.content_type`, que no siempre es JSON. ## Consultar una tarea Agrega el identificador de la tarea a la misma ruta del endpoint: ```shell curl "https://runapi.ai/api/v1/flux_2/text_to_image/task_id" \ -H "Authorization: Bearer YOUR_API_TOKEN" ``` Continúe mientras `status` sea `processing`. Use un retroceso acotado entre solicitudes en lugar de consultar continuamente. Una Tarea se vuelve terminal cuando su estado es `completed` o `failed`. ## Manejar la finalización Una respuesta `completed` incluye el `id` de la tarea, el `status` terminal y los campos de resultado específicos del endpoint. Conserva el resultado que necesitas y deja de hacer polling. Consulta la Referencia de la API del endpoint para conocer la estructura exacta del resultado en lugar de asumir que todos los endpoints de medios devuelven los mismos campos. ## Manejar fallos Una respuesta `failed` incluye el `id` de la tarea, el `status` terminal y un `error` generado por RunAPI cuando está disponible. Deja de hacer polling, registra el identificador y el error, y reintenta solo cuando tu aplicación haya clasificado el fallo como transitorio. Un reintento crea un nuevo identificador de tarea. ## Recibir una devolución de llamada Agrega una `callback_url` HTTPS pública a la solicitud de creación cuando quieras que RunAPI envíe los eventos de devolución de llamada documentados para ese endpoint: ```json { "model": "flux-2-pro-text-to-image", "prompt": "A product photograph on a clean studio background", "callback_url": "https://your-domain.com/webhooks/runapi" } ``` Cada cuerpo de devolución de llamada coincide con un evento del ciclo de vida en la Referencia de la API del endpoint y omite los detalles de facturación exclusivos del sondeo. Las devoluciones de llamada terminales incluyen los mismos campos de resultado que las respuestas de sondeo terminales; algunos endpoints también envían devoluciones de llamada `processing` documentadas. Devuelva una respuesta HTTP exitosa rápidamente y mantenga el sondeo disponible para la reconciliación cuando la entrega se retrase o su manejador de devoluciones de llamada no esté disponible. Lea [Devoluciones de llamada](https://runapi.ai/es/docs/guides/task-api/callbacks.md) para crear un secreto de devolución de llamada, verificar firmas y gestionar los reintentos de forma segura. --- ## Más de RunAPI - [Inicio](https://runapi.ai/es/.md) - [Catálogo de modelos](https://runapi.ai/es/models.md) - [Precios](https://runapi.ai/es/pricing.md) - [Proveedores](https://runapi.ai/es/models) - [Documentación](https://runapi.ai/es/docs/guides) - [SDKs](https://runapi.ai/es/sdk.md) - [CLI](https://runapi.ai/es/cli.md) - [Servidor MCP](https://runapi.ai/es/mcp.md) - [Claude Code vs Cursor](https://runapi.ai/es/claude-code-vs-cursor.md) - [Configuración de Cursor API](https://runapi.ai/es/cursor-api-setup.md) - [RunAPI vs OpenRouter](https://runapi.ai/es/openrouter-alternative.md) - [Enterprise](https://runapi.ai/es/contact.md) - [Contacto](https://runapi.ai/es/contact.md) - [Términos](https://runapi.ai/es/terms.md) - [Privacidad](https://runapi.ai/es/privacy.md) - [Índice del sitio para agentes](https://runapi.ai/llms.txt) Contacto: contact@runapi.ai ## Datos estructurados ```json [ { "@context": "https://schema.org", "inLanguage": "es", "@type": "WebSite", "name": "RunAPI", "url": "https://runapi.ai/es", "potentialAction": { "@type": "SearchAction", "target": { "@type": "EntryPoint", "urlTemplate": "https://runapi.ai/es/models?q={search_term_string}" }, "query-input": "required name=search_term_string" } }, { "@context": "https://schema.org", "inLanguage": "es", "@type": "Organization", "name": "RunAPI", "url": "https://runapi.ai/es", "logo": { "@type": "ImageObject", "url": "https://runapi.ai/esicon.svg" }, "sameAs": [ "https://github.com/runapi-ai" ] }, { "@context": "https://schema.org", "inLanguage": "es", "@type": "TechArticle", "headline": "Inicio rápido", "description": "Cree una Tarea asíncrona y gestione el sondeo, la finalización, los fallos y las devoluciones de llamada.", "url": "https://runapi.ai/es/docs/guides/task-api/quickstart", "mainEntityOfPage": "https://runapi.ai/es/docs/guides/task-api/quickstart" } ] ```