API sandbox environment: test a paid API without paying

An API sandbox environment is a separate copy of an API, with its own test credentials, where calls return fake or free results and nothing real is charged or delivered. It lets you build and run integration tests before you switch to live keys. Not every paid API has one. Sume doesn't document a sandbox or test keys: its keys are sume_live_…, and a paid generation call reserves real money from the workspace balance. Where Sume's docs say a Format run happens "in a fresh sandbox", they mean an isolated workspace for that run, not a free test mode.

You can still test most of an integration against Sume without paying for generation, and cap what the rest costs. The facts below come from Authentication, the API reference, Generation admission, Create a run and MCP tools and gates, all read on 2026-09-29.

What does an API sandbox give you?

Without one, you rebuild those three properties yourself: a mock for your automated tests, free calls for checking the contract, and a small, capped budget for the few end-to-end runs that need real output.

• Separate credentials, so test traffic can't touch production data or money.
• Predictable responses, including forced errors, so tests are repeatable.
• No charges, so a test suite can run on every commit.

How do I test against Sume without a sandbox?

Split the work by what it needs from the real API.

How do I mock the API in automated tests?

Build a local stub from the OpenAPI document and point your client's base URL at it in tests. Download it from GET /v1/openapi.json without a key, or read it at the API reference. Make the stub answer the way the real API does for async work: a submit returns a job id right away, and your code polls for the result. Script failures too, such as 429 rate_limited with retry-after, 402 insufficient_credits and 409 idempotency_conflict, so your retry and error code runs in CI without a live call.

A few Sume checks are unbilled, such as the Timeline plan and the video filter check; free and flat-fee Sume API calls lists them. To test a webhook receiver, see free webhook tester.

Can I use a separate API key for testing?

Yes, but it isn't a sandbox. Keys are workspace-scoped, and balance is the spendable USD balance of the authenticated workspace, so a test key in the production workspace spends the same money. A separate key still helps: you can revoke it without touching production, and Sume's docs advise the narrowest scopes a client needs, which are fixed when the key is created.

For the end-to-end runs that must produce real output, keep them few and capped. Sume's best-practices page says to always set generation_spend_cap_usd and to treat a missing cap as a bug in the client. Send an Idempotency-Key on every create, so a retried test doesn't pay twice; see idempotency keys.