> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noimosai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestionar ejecución y facturación

> Ejecución asíncrona, reintentos idempotentes, reservas, liquidación y descarga de artefactos.

## Descripción general

Esta página explica presupuesto, reserva, ejecución asíncrona, liquidación y artefactos. Sigue los procesos largos por su ID en lugar de mantener abierta la conexión HTTP.

## Entender ejecución y facturación

`POST /tools/quote` devuelve versión de precios, cargo mínimo y reserva máxima para la entrada. El presupuesto es gratuito: no invoca servicios externos ni reserva fondos.

Conserva `tool` y `arguments` del presupuesto y añade:

* `priceVersion` — Versión de precios del presupuesto
* `maximumChargeMicros` — Reserva máxima del presupuesto

Si cambian los precios o el límite no basta, se rechaza la solicitud sin iniciar el proceso. Obtén y revisa un nuevo presupuesto.

## Reservar y liquidar cargos

Al aceptar trabajo de pago se retiene temporalmente la reserva máxima del saldo prepagado en USD. Al terminar, se liquida el coste real y se devuelve la parte no utilizada.

| Campo | Significado |
| - | - |
| `reservedMicros` | Máximo reservado al aceptar; conserva su valor original tras finalizar. |
| `chargedMicros` | Cargo definitivo después de finalizar o fallar. `0` durante el proceso significa que falta liquidar. |
| `currency` | `usd`. 1 USD equivale a 1,000,000 micros. |

Aunque falle o se cancele, se liquidan los costes externos ya incurridos. Nunca se cobra automáticamente por encima de la reserva máxima.

## Consultar el estado

La aceptación devuelve HTTP 202 y un ID. Sigue `Retry-After: 5` y consulta el mismo ID a intervalos de al menos cinco segundos.

| Estado | Significado | Acción |
| - | - | - |
| `queued` | En cola | Esperar al menos cinco segundos y consultar |
| `running` | En proceso | Consultar el mismo ID |
| `waiting` | Esperando procesamiento externo | Consultar el mismo ID |
| `succeeded` | Correcto y liquidado | Leer `output` y `chargedMicros` |
| `failed` | Fallido; costes incurridos liquidados | Leer `errorCode` y cargo definitivo |
| `cancelled` | Cancelación completada | Revisar cargo definitivo |
| `needs_review` | Resultado o coste pendiente de revisión | No repetir; contactar con soporte con el ID |

## Evitar duplicados mediante idempotencia

Una clave de idempotencia evita crear ejecuciones distintas al reenviar accidentalmente una solicitud. `POST /tools/{tool}` de pago requiere `Idempotency-Key`.

La clave debe tener 8–128 caracteres: letras, números, `.`, `_`, `:` o `-`. Genera una por solicitud lógica y guárdala con el ID de ejecución.

* La misma clave API, cuerpo y clave de idempotencia devuelven la misma ejecución.
* Cambiar cuerpo o clave API manteniendo la clave de idempotencia devuelve HTTP 409.
* Tras un fallo de conexión, reenvía sin cambiar cuerpo ni clave de idempotencia.
* Reenviar un proceso `needs_review` con una clave nueva crea otra ejecución de pago.

> [!WARNING]
>
> No recibir respuesta no demuestra que la ejecución no se aceptara. No crees otra clave si desconoces el resultado.

## Cancelar una ejecución

`POST /tools/executions/{id}/cancel` solicita detener trabajo aún no iniciado. Puede hacerlo la clave creadora o un `ADMIN` del proyecto.

Si el procesamiento externo ya empezó, la cancelación puede no deshacer el trabajo ni sus cargos. Revisa `cancelRequested`, el `status` final y `chargedMicros`.

## Obtener artefactos

Las imágenes, audio y vídeos generados aparecen en `output.artifacts` con ID, formato, tamaño, hash y vencimiento. El resultado no contiene archivos completos ni URL permanentes.

`GET /tools/executions/{id}/artifacts/{artifactId}/download` devuelve una URL válida hasta cinco minutos. Los archivos almacenados caducan a los 30 días.

Las URL temporales dan acceso a datos privados. No las registres ni publiques, ni les añadas la clave de Developer Platform.

## Páginas relacionadas

Consulta estas páginas para la primera ejecución y los endpoints.

* [Primeros pasos](https://docs.noimosai.com/es/developers/api/getting-started.md)
* [Referencia de la API](https://docs.noimosai.com/es/developers/api/reference.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.