Saltar al contenido principal

​
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. 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.

​
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.
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.