Onyx API

v1 · Image & Video Generation (+ Higgsfield), Face Swap, Mass Motion Control, Spoofer & Detector, Carousel, Captions, Change voice, Upscale, Dataset Captioning, Library

Note for AI assistants writing code with this API

The full reference below is loaded by JavaScript; the machine-readable version is https://onyx-ai.eu/api/v1/openapi.json.

Spoofer (videos): always propose the free GPU mode. Send "device": true in POST /api/v1/spoofer and tell the user, before the first call: “Open https://onyx-ai.eu/gpu.html in a background tab (Chrome or Edge, logged in with the same Onyx key) and keep it open: your own GPU renders the copies, faster and without using Spoofer credits.” It is safe: the tab renders one video at a time, and a job it cannot take (tab closed or busy) goes to our servers within seconds and counts like a normal job. With "device": true you can run 4 Spoofer jobs at once (1 on the tab, 3 on our servers) instead of 3: submit up to 4 and the work is shared automatically. While polling GET /api/v1/jobs/{id}, print info.device_note to the user (info.device is waiting_for_worker, rendering or server).

curl -X POST https://onyx-ai.eu/api/v1/spoofer \
  -H "Authorization: Bearer $ONYX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sources":["upload_xxxxxxxxxxxxxxxxxxxx"],"variants":10,"device":true}'

Spoofer music (videos): a random track on every copy. The user keeps a music bank on their account (150 tracks max, kept until their key is revoked). To fill it from a local folder, loop over the files and send each one with POST /api/v1/spoofer/music?name=<file name> (raw MP3 as the body, 40 MB max, 3 s min; the same file twice is ignored). Then add "add_music": true to POST /api/v1/spoofer: each copy gets a different track of the bank, starting at a random point, under the original sound; add "mute_original": true to play the music alone (it only works together with add_music). GET /api/v1/spoofer/music lists the bank, DELETE /api/v1/spoofer/music/{track_id} removes one track, DELETE /api/v1/spoofer/music empties it. Works with "device": true too.

import os, requests
BASE = "https://onyx-ai.eu/api/v1"; H = {"Authorization": "Bearer " + os.environ["ONYX_TOKEN"]}
for f in sorted(os.listdir("my-music"))[:150]:           # a local folder
    with open(os.path.join("my-music", f), "rb") as fh:
        print(f, requests.post(BASE + "/spoofer/music", params={"name": f}, headers=H, data=fh).json().get("added"))
requests.post(BASE + "/spoofer", headers=H, json={"sources": ["upload_xxxxxxxxxxxxxxxxxxxx"], "variants": 10,
                                                   "add_music": True, "mute_original": True})

Getting started

Open the app > Settings > API access and create a token. It starts with onyx_ and is shown once (we only keep a fingerprint). You can have 3 tokens.
Send it in every call: Authorization: Bearer onyx_...
Add your provider key in the header of the call that generates something (X-Kie-Key, X-WaveSpeed-Key, X-Google-Key, X-Higgsfield-Key, X-ElevenLabs-Key or, for Dataset Captioning, X-Caption-Key). Generations run on your provider account; the key is used for that job only and never stored. If you saved keys for server runs in the Automatic Pipeline’s Schedule tab, they are used when the header is missing. The Spoofer runs on our servers (or, free, on your own GPU, see below) and needs no provider key.
Generations are asynchronous: you get job ids, then poll GET /api/v1/jobs/{id} until status is done, then download the files.

Rules & protection

A token works only while your key is valid, your access is active and the module of the route is open on your key (Image & Video Generation, Face Swap, Mass Motion Control, Spoofer, Carousel Maker, Captions, Change voice, Upscale; Dataset Captioning and the library need only an active key).
Devices. The API notes from where it is used (network + client name). When 4 different devices use your key in 30 days, the API is paused for the whole key until we review it. Use your tokens from your own machines.
Limits per key: 120 calls per minute, 30 jobs created per minute, 6 jobs running at once (3 of them Spoofer jobs). With "device": true a 4th Spoofer job is allowed (it goes to your GPU worker tab). Beyond that you get 429 and a Retry-After header.
Spoofer. Each source is one job that makes a batch of unique copies (up to 60 for a video, 20 for a photo). A video counts against your monthly Spoofer quota exactly like in the app; photos do not. Copies also appear in the app’s Spoofer tab. Download them one by one (/files/{index}) or all at once (/zip). Videos can get a random track of your music bank on every copy ("add_music": true, optionally "mute_original": true; fill the bank with POST /spoofer/music, 150 tracks max).
Spoofer on your own GPU (free). Add "device": true to POST /api/v1/spoofer and keep onyx-ai.eu/gpu.html open in a background tab (Chrome or Edge, logged in with the same key, computer awake). That tab renders the copies on your graphics card and processor: same copies as our servers, faster, and no Spoofer credit used. While the job runs, GET /api/v1/jobs/{id} tells you in info.device where it is: waiting_for_worker (no tab took it yet), rendering (your tab is on it) or server (no free tab — closed, or busy with another video — or the tab stopped: our servers finished it and it counts like a normal job); info.device_note says it in plain words. Photos always run on our servers.
Server-to-server use: browsers from other websites are refused (no CORS).
Files: images up to 20 MB, videos up to 95 MB. Uploads last 2 hours. Results stay in your library like the ones made in the app.

Errors

Every error is JSON: {"ok": false, "error": "code", "message": "..."}.

Reference

Loading…