Test mode

What a test key does

A key starting smol_test_ calls the same endpoints as a live key and runs the same engine. Nothing is mocked: the file you get back is a real result, produced with the options you sent. The response headers, the result object and the errors are the ones you will see in live mode.

There are three differences:

• A test key only accepts the published sample files. Any other file is refused.
• Test requests are free. Smol-Billed is always false, and a test job always has billed: false.
• Test keys work as soon as the account exists. No payment method is needed.

Sample files

A sample file is recognised by the SHA-256 of its bytes. The name of the file does not matter. The bytes do: if you open a sample and save it again, or let a tool re-encode it, the hash changes and the file is no longer a sample. Download the files and send them unchanged.

There are 16 samples, one or more for each kind of file the API handles. The same list, with every hash, is at /api-samples/manifest.json.

curl -O https://smolmac.com/api-samples/photo.jpg
shasum -a 256 photo.jpg
# dc57e874fed9ea671f5bcb57e68d7148e2ac09c0f6d3bf5cb647b33d6af8970a

A file that is not on the list is refused with 402:

{
  "error": {
    "type": "billing_error",
    "code": "test_mode_sample_required",
    "message": "Test keys only work with the published sample files. Use a live key for your own files.",
    "param": null,
    "request_id": "req_Q2mY8sLx0aVn4TfB7kRd",
    "doc_url": "https://smolmac.com/docs/reference/errors#test_mode_sample_required"
  }
}

Try it

Send a sample file exactly as you would send your own. Options work as usual, so you can test every format and setting that applies to the sample.

export SMOL_API_KEY="smol_test_..."

curl -X POST "https://api.smolmac.com/v1/compress?image.format=avif&image.quality=60" \
  -H "Authorization: Bearer $SMOL_API_KEY" \
  --data-binary @photo.jpg \
  -o photo.avif -D -

HTTP/1.1 200 OK
Content-Type: image/avif
Smol-Output-Format: avif
Smol-Kept-Original: false
Smol-Billed: false
RateLimit-Limit: 4
RateLimit-Remaining: 3
RateLimit-Reset: 1

Some samples need a little more than the file:

Limits in test mode

The test rate limit is separate from the live one. Test traffic does not use up the rate allowance of your live keys.

Jobs and webhooks

Jobs work in test mode. Upload a sample file, create a job, and poll it or receive a webhook, exactly as in Large files and jobs. A job created with a test key carries livemode: false:

{
  "id": "job_4tGZq0WnB8sYh2LdX6pC",
  "object": "job",
  "livemode": false,
  "operation": "compress",
  "status": "succeeded",
  "billed": false
}

The two modes are kept apart:

• A test key cannot read, download, delete or get a receipt for a live job. The API answers 404 not_found, as if the job did not exist. A live key cannot see test jobs either.
• GET /v1/jobs lists only the jobs of the mode of the key that asks.
• Webhook endpoints belong to the account, not to a mode. They receive events for test jobs and live jobs. Each event has a livemode field, so check it before you act on an event.

Going live

1. Add a payment method or choose a plan in the dashboard.
2. Create a live key.
3. Replace the test key with the live key in your configuration. No other change is needed: the endpoints, the options and the responses are the same.

Keep a test key in your automated tests. The sample files do not change, so a test that sends a sample has a stable input and costs nothing to run. Usage made with a test key is reported separately: GET /v1/usage with a test key returns test usage only.