Skip to main content

​
Overview

This page follows paid tools from quoting through reservation, asynchronous execution, settlement, and artifact retrieval. Track long-running work by execution ID instead of keeping an HTTP connection open.

​
Understand execution and billing

POST /tools/quote returns the price version, minimum charge, and maximum reservation for the current input. Quotes are free: they neither invoke external services nor reserve funds. To execute, use the same tool and arguments as the quote and add these two fields:
  • priceVersion — The price version returned by the quote
  • maximumChargeMicros — The maximum reservation returned by the quote
If prices have changed or the supplied cap is too low, the request is rejected before work starts. Obtain a new quote and review it again.

​
Reserve and settle charges

When paid work is accepted, the maximum reservation is temporarily held from the prepaid USD balance. After completion, the actual charge is settled and the unused reservation is returned to the balance. Failures and cancellations can still settle actual costs already incurred by external processing. Charges never automatically exceed the maximum reservation.

​
Track execution status

Acceptance returns HTTP 202 and an execution ID. Follow Retry-After: 5 and poll the same ID at intervals of at least five seconds.

​
Prevent duplicates with idempotency keys

An idempotency key identifies a request so that accidentally sending it multiple times does not create separate executions. Paid POST /tools/{tool} requests require the Idempotency-Key header. Keys must be 8–128 characters using letters, digits, ., _, :, or -. Generate one per logical request and store it with the execution ID.
  • Resending the same API key, body, and idempotency key returns the same execution.
  • Changing the body or API key while reusing the idempotency key returns HTTP 409.
  • After a connection failure, resend without changing the body or idempotency key.
  • Resending a needs_review request with a new idempotency key creates another paid execution.
A missing response does not prove that the execution was not accepted. Do not create a new idempotency key when the outcome is unknown.

​
Cancel an execution

POST /tools/executions/{id}/cancel requests that work which has not started be stopped. The key that created the execution or a project ADMIN can request cancellation. Once external processing has started, a cancellation request may not undo the work or its cost. Check cancelRequested and the final status and chargedMicros.

​
Retrieve artifacts

Generated images, audio, and video appear in output.artifacts as file IDs, formats, sizes, hashes, and expiration dates. The execution result does not contain file contents or permanent URLs. Call GET /tools/executions/{id}/artifacts/{artifactId}/download to obtain a download URL valid for up to five minutes. Stored files expire after 30 days. Even temporary download URLs grant access to private data. Do not log or publish them, and do not append the Developer Platform API key to them. See these pages for your first execution and endpoint details.