Overview

The Nureta Developer API turns prompts and reference media into video, images and scripts. Every endpoint shares one authentication model, one task lifecycle (create → poll → terminal), and one set of callbacks and errors — all documented on this page. The per-medium specifics live under Video, Image and Script.

SDKs

Official clients wrap authentication, task creation and polling so you don't hand-roll the REST calls:

Prefer raw HTTP? Every example below is plain curl.

Base URL

All endpoints are served from https://developer.nureta.ai. The examples use a $TOKENSTORE_URL shell variable for it — set it once:

export TOKENSTORE_URL="https://developer.nureta.ai"

Authentication

All requests authenticate with an API key (create one under API keys). Pass it as a bearer token. Generations are billed to your balance at the posted model prices; insufficient balance returns an AccountOverdueError.

Authorization: Bearer sk-...
Content-Type: application/json

Rate limits

Every request made with an API key counts toward that key's rate limit — including task creation, status polling, storyboard edits and uploads. New keys default to 10 requests/second; you can adjust each key between 1 and 100 req/s on the API keys page. Exceeding the limit returns 429 RateLimitExceeded with standard RateLimit headers — back off briefly and retry. Upload presigning additionally has a fixed cap of 30 requests/minute per key.

Upload a reference image

POST /api/v3/contents/uploads — use this when you don't already host your reference image at a public URL. Ask for a short-lived signed URL, PUT the image bytes straight to storage, then pass the returned assetUrl as an image_url.url in a generation task. Authenticated with your API key; uploading is free (you are billed only when you create a generation).

# 1. Ask for a signed upload URL.
UPLOAD=$(curl -s -X POST "$TOKENSTORE_URL/api/v3/contents/uploads" \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"fileName": "ref.jpg", "contentType": "image/jpeg"}')
# => {"uploadUrl": "https://...signed...", "assetUrl": "https://.../ref.jpg"}

# 2. Upload the bytes to the signed URL (same Content-Type, no auth header).
UPLOAD_URL=$(echo "$UPLOAD" | jq -r .uploadUrl)
ASSET_URL=$(echo "$UPLOAD" | jq -r .assetUrl)
curl -s -X PUT "$UPLOAD_URL" -H "Content-Type: image/jpeg" --data-binary @ref.jpg

# 3. Reference ASSET_URL as an image_url when creating a generation task:
#    {"type": "image_url", "image_url": {"url": "'"$ASSET_URL"'"}}

Both body fields are optional: fileName (used to derive the stored object name) and contentType — which must match the Content-Type you send on the PUT, because it is signed into the URL. The signed URL is short-lived, so request a fresh one per file.

Callback webhook

When callback_url is provided on task creation, Nureta Developer POSTs the terminal task object to that URL when the task becomes succeeded or failed. The JSON body is exactly the same public object returned by retrieving the task.

Callback delivery is at-least-once. Receivers should deduplicate by id. Failed deliveries are retried up to 5 attempts; a delivery is successful when the endpoint returns any 2xx status. The request times out after 5 seconds and redirects are not followed.

Edit-mode draft-ready event. If an edit-mode task has a callback_url, a best-effort X-Tokenstore-Event: generation.task.planned webhook fires once when the storyboard draft is ready (the body carries status: "planned" and the scene). It is not retried and is separate from the terminal generation.task.completed event, which still fires after you render.

POST /webhooks/nureta-developer HTTP/1.1
Content-Type: application/json
User-Agent: tokenstore-webhook/1.0
X-Tokenstore-Event: generation.task.completed
X-Tokenstore-Task-Id: cgt-...
X-Tokenstore-Delivery: 00000000-0000-0000-0000-000000000000
X-Tokenstore-Timestamp: 1781220120
X-Tokenstore-Signature: sha256=<hex-hmac>  # only when callback_secret was provided

Signature verification. When callback_secret was provided, compute an HMAC-SHA256 over timestamp + "." + rawBody using the secret, and compare it (constant-time) against the hex digest in X-Tokenstore-Signature.

Safety rules for callback_url: must use HTTPS; must not include credentials; must not target localhost or private, loopback, link-local, multicast or otherwise reserved IP ranges.

Errors

Errors return a JSON body with a code and message:

• AuthenticationError — missing or invalid API key.
• InvalidParameter — a request field is missing or invalid (e.g. "duration must be one of 5, 8, 10, 12, 15 seconds (single clip) or an integer from 16 to 180 seconds (multi-segment scene)").
• ModelNotFound — unknown model id.
• AccountOverdueError — insufficient balance to reserve the task.
• RateLimitExceeded (HTTP 429) — the key's requests-per-second limit was hit; see Rate limits.
• InternalServiceError — generation failed; "Generation failed. You have been refunded."