Conventions
Rules that apply to every endpoint.
Requests and responses
| Item | Convention |
|---|---|
| Protocol | HTTPS only. |
| Format | JSON in UTF-8. Requests with a body must send Content-Type: application/json. |
| Base URL | https://api.nanoapi.ai/v1 |
Times
ISO 8601 strings in UTC, for example 2026-10-22T08:30:00Z. Two headers use Unix seconds instead: X-RateLimit-Reset and the webhook webhook-timestamp header.
Amounts
US dollars, as decimal strings with up to 6 decimal places, for example "1.50" or "0.05". In billing, only billed_seconds is a number rather than a string (up to 3 decimal places).
Don't parse amounts as floating-point numbers. Use a decimal type, such as decimal.Decimal in Python or a decimal library in JavaScript.
IDs
IDs are lowercase, with a short prefix for the object type.
| Object | Prefix | Example |
|---|---|---|
| Task | tk_ | tk_01jb8z5q4w3e2r1t0y9u8i7o6p |
| API key | ak_ | ak_01jb7y2m3n4p5q6r7s8t9v0w1x |
| Webhook event | ev_ | ev_01jb9a3k7m2n5p8q4r6s1t0v9w |
| Request | rq_ | rq_01jb... |
Older objects keep their original IDs (such as task_01JB…) and still work. Treat IDs as opaque strings: don't parse the prefix or change the case, and send them back exactly as you received them. The full API key itself still starts with nf_.
Request IDs
Every response has an X-Request-Id header, repeated in error responses as error.request_id. Log it and include it when you contact support.
Versioning
The version is in the path (/v1).
- New fields aren't a breaking change and don't change the version. Ignore fields you don't recognize, in responses and webhook payloads.
- Breaking changes ship as a new version,
/v2.
Unknown request parameters, however, return 400 invalid_request.
Timeouts
Creating a task reads the source video first, usually in 1–3 seconds and at most about 35: set your client timeout to 60 seconds or more.
Pagination
List endpoints use cursor pagination.
| Parameter | Description |
|---|---|
limit | Items per page. Default 20, maximum 100. |
starting_after | The id of the last item on the previous page. The response starts with the item after it. |
{ "object": "list", "data": [], "has_more": true }Stop when has_more is false. Read endpoints allow 1 request per second, so space out page requests (Rate limits).
curl "https://api.nanoapi.ai/v1/tasks?limit=100&starting_after=tk_01jb8z5q4w3e2r1t0y9u8i7o6p" \
-H "Authorization: Bearer $NANOAPI_API_KEY"