|
Developer API · One key per account

Your API key.

Generate your personal TikQuick API key and use it with the third-party endpoints.

Loading…

Docs · OTU upload flow

API docs

Everything below runs against https://api.tikqcapi.site (Passport) and https://byte.tikqcapi.site (processing server). The optional Optimize step uses one of two encoder servers (https://vapi.tikqcapi.site and https://vapi2.tikqcapi.site), reached with a token from your key. Pick the less busy one for each job, see section 7.

1. Getting a key

  1. Sign in, then press Generate API key in the panel on the left.
  2. One key per account, one key per IP. Fresh keys allow 10,000 uses, Premium keys are unlimited.
  3. Copy it somewhere safe. It never expires and never needs rotating unless it leaks.

2. Keep it secret

Do not put your key in client-side code, no frontend JS, no shipped browser extension, no public repo. Keep it on your server and only ever send the short-lived OTU tokens (section 3) to the browser. Anyone with the key can mint tokens as you. If it leaks, hit Remake: the old key dies instantly and you get a fresh one with the same usage, cap and Premium status carried over, remaking never resets your limits.

3. Mint an OTU token

Every upload starts by trading the key for a fresh single-use token. The key itself never goes to PS.

GET https://api.tikqcapi.site/passport/api/thirdparty/genotu?key=YOUR_KEY
{ "token": "a1b2c3...(64 hex chars)", "user_id": "u...", "username": "9f2c...(anonymous key username)", "expires_at": "2026-07-31 15:00:00" }
400Missing key, no key supplied
403Invalid API key / key disabled (banned)
429Usage limit reached (free 10k cap spent)
500Key misconfigured, contact us on Discord

Tokens are single-use and short-lived, mint one right before each upload, never cache them. Save user_id + token for the next step.

4. Patch methods

Every patch request (/api/v2/patch and /api/upload/init) takes a selectmethod query parameter. Append it after the auth params.

orionDefault. Use this whenever you can. The video should be uploaded to TikTok as "Everyone" or "Friends Only", not "Only Me".
lunaFallback if Orion does not work for a video. Risky patch, and it requires a 60 or 30fps source.
...&selectmethod=orion ...&selectmethod=luna

Anything other than luna should be sent as orion. Show the matching warning above to your users when they pick a method.

5. Instant patch (header-only)

The fast path. Only the MP4 header goes to the server, never the video itself. The server returns a patched header plus a small "ghost sample", and you splice the final file locally. Nothing is re-encoded and no chunking is needed.

final = patched_prefix + original_mdat_payload + ghost_sample

Step A, check the layout locally first. Do this before minting an OTU token, because every answered request (even a 4xx) spends the token. Walk the top-level MP4 boxes by reading only their headers:

  • Exactly one moov and one mdat, and no moof / mfra / sidx boxes (so no fragmented MP4).
  • Faststart layout: moov comes before mdat, and mdat runs to the end of the file with nothing after it.
  • The prefix is everything up to and including the mdat box header. It must be 64MB or smaller, moov must be 64MB or smaller, and the whole file 400MB or smaller.
  • moov must not contain an mvex box.
  • Common phone layout (mdat then moov at the end): reorder locally to moov then mdat. This is a pure box shuffle, no re-encode. Add the moov size to every offset in each stco / co64 table, and check each offset still points inside the mdat payload (and stays under 2^32 for stco). If anything is unusual, give up and use the chunked fallback (section 6).

Step B, send the prefix.

POST https://byte.tikqcapi.site/api/v2/patch?auth_userid=USER_ID&auth_token=TOKEN&selectmethod=orion Content-Type: application/octet-stream X-Original-File-Size: TOTAL_SIZE_OF_FASTSTART_FILE Body: the prefix bytes only
{ "patched_prefix_b64": "...", "patched_prefix_size": 1234, "client_prefix_size": 1200, "ghost_sample_hex": "...", "ghost_offset": 98765, "final_size": 98777 }

Step C, assemble and verify. Base64-decode patched_prefix_b64, hex-decode ghost_sample_hex, then build the final file from the three parts above (the payload is the faststart file from byte prefixLen onward, untouched). Reject the result if any of these fail:

  • client_prefix_size equals the prefix length you sent.
  • Decoded prefix length equals patched_prefix_size.
  • Final file size equals final_size.
  • ghost_offset equals final_size minus the ghost length.
400Server rejected the video header
401 / 403 / 503Authentication failed, mint a fresh token and retry
413Video too large for the patch server
422Video cannot be patched as-is
501Patch mode not supported by this server, use the chunked fallback

6. Chunked upload (fallback)

Use this when the instant patch (section 5) is not possible for a file. Files are split into 20MB or smaller chunks, POSTed individually (a single-shot upload of anything but small files will fail). 2 chunks in flight at once with retry + backoff works well.

POST https://byte.tikqcapi.site/api/upload/init?auth_userid=USER_ID&auth_token=TOKEN&selectmethod=orion {"filename": "myvideo.mp4", "total_size": 123456789, "total_chunks": 7} -> { "job_id": "...", "job_otu": "..." }
POST https://byte.tikqcapi.site/api/upload/chunk?job_id=JOB_ID&job_otu=JOB_OTU&chunk_index=N Body: raw bytes of chunk N (repeat per chunk)
POST https://byte.tikqcapi.site/api/upload/complete?job_id=JOB_ID&job_otu=JOB_OTU -> the patched video, streamed back as binary

Use job_id / job_otu (not your original token) for chunks and complete. Track progress in bytes sent, not chunks finished, for a smooth bar.

7. Optimize (TikTok encoder)

Optional pre-pass for videos that have not been compressed or exported (for example from Handbrake) yet, and the only route for files over 400MB (up to 1500MB). It adds a few seconds to processing. The result is then fed into the normal PS patch with an enc_id instead of raw chunks. Skip the instant patch for these files.

The encoder token is minted with your API key, the same key as the OTU token. Keep it server-side.

  1. Pick the least busy encoder. There are two, vapi and vapi2. Ask each how loaded it is (no key needed, and it does not cost a use):
    GET https://vapi.tikqcapi.site/loadz -> { "load": "31.4" } GET https://vapi2.tikqcapi.site/loadz -> { "load": "12.0" }

    load is how busy that server is, 0 to 100, sent as a string (parse it as a number). Use the lowest. A value of 91 or more means jobs are already waiting in a queue there, so avoid it unless the other is just as bad. If the two are within a couple of points, either is fine. Give each call a short timeout (about 3 seconds) and if one does not answer, use the other. Do this right before you mint the token. One reading is good for about 5 seconds, so you do not need to re-check for every request.

  2. Get an encoder token for the server you picked (costs 1 use of your key, same as an OTU token):
    GET https://api.tikqcapi.site/passport/api/thirdparty/genenc?key=YOUR_KEY -> { "token": "...", "encoder_server": "https://vapi.tikqcapi.site" }
    GET https://api.tikqcapi.site/passport/api/thirdparty/genenc?key=YOUR_KEY&encoderserver=vapi2 -> { "token": "...", "encoder_server": "https://vapi2.tikqcapi.site" }

    Leave encoderserver off for vapi, and send &encoderserver=vapi2 for vapi2. A token only works on the server that minted it, so use the returned encoder_server as ENCODER_SERVER for every remaining step of that job (create, upload, finish, progress).

    400Missing key, or an unknown encoderserver value
    403Invalid API key / key disabled (banned)
    429Usage limit reached
    500Key misconfigured, contact us on Discord
    502Could not reach that encoder server. Retry, or mint a token for the other one (every attempt costs 1 use)
  3. Create a job:
    POST ENCODER_SERVER/api/make?token=ENC_TOKEN -> { "jobid": "...", "jobtoken": "..." }
  4. Upload in 5MB chunks, numbered from 1 (retry with backoff):
    POST ENCODER_SERVER/api/upload/N?jobid=JOBID&jobtoken=JOBTOKEN Content-Type: application/octet-stream Body: raw bytes of chunk N
  5. Finish the upload:
    POST ENCODER_SERVER/api/upload/finish?jobid=JOBID&jobtoken=JOBTOKEN -> { "status": "queued", "sse": "/relative/progress/url" }
  6. Follow the progress stream (server-sent events, GET ENCODER_SERVER + sse). Each message is a line starting with data: followed by JSON with an event field:
    queuedHas pos and optional eta_seconds
    setting_up_env, rendering, processingProgress, optional percent and message
    doneHas output_url_base64, base64-decode it to get the output URL
    failedHas error, stop
  7. Pull the UUID (enc_id) out of the decoded output URL, then patch it on PS. PS downloads the encoded file from the encoder that made it, so tell it which one with enc_serve:
    POST https://byte.tikqcapi.site/api/upload/init?auth_userid=USER_ID&auth_token=TOKEN&selectmethod=orion {"filename": "ENC_ID.mp4", "total_size": 1, "total_chunks": 1} -> { "job_id": "...", "job_otu": "..." }
    GET https://byte.tikqcapi.site/api/upload/complete?job_id=JOB_ID&job_otu=JOB_OTU&enc_id=ENC_ID -> the patched video, streamed back as binary
    GET https://byte.tikqcapi.site/api/upload/complete?job_id=JOB_ID&job_otu=JOB_OTU&enc_id=ENC_ID&enc_serve=vapi2 -> same, but PS pulls the encoded file from vapi2
    enc_serveWhich encoder PS pulls enc_id from. Either vapi or vapi2. Leave it off for vapi (the default).

    Send &enc_serve=vapi2 if, and only if, the job ran on vapi2 (the token came from encoderserver=vapi2). The file only exists on the encoder that produced it, so a mismatch returns a 502. Any value other than vapi or vapi2 returns a 400.

The encoders are sometimes down. The two /loadz checks above double as the availability check: if neither answers, fall back to the direct limits (300MB, or 400MB with the partner perk).

8. Health check

GET https://byte.tikqcapi.site/api/psver -> { "online": true, "server_location": "...", "ps_version": "..." }

No auth needed, good for a "test connection" button. Having trouble? Try https://ps.tikquick.online as a backup PS domain (or https://tqps.exliatycl.online).

How it works

Create

One key per account, one key per IP. Your key is capped at 10,000 uses unless an admin marks it Premium.

01

Use

Pass your key to the third-party endpoints to mint upload tokens.

GET /passport/api/thirdparty/genotu?key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.0000000000000000000
02

Limits

Free keys stop minting after 10,000 uses. Premium keys are unlimited. Think your key leaked? Hit Remake above, the old key dies instantly and you get a fresh one. Get a premium key via DM'ing @mikedev_ on our Discord server..

03