Submit a Song Job

POST /api/v1/tiktok/song — 1 credit per request

Look up a TikTok song / clip by its clipId. The result is the TikTok music_info JSON, close to as returned by TikTok’s own web app.

Note

All requests require your Megomi API key, via either the Authorization: Bearer <key> header or the X-API-Key header.

Endpoints

Method	Path	Returns
POST	/api/v1/tiktok/song	Submit a song lookup
GET	/api/v1/tiktok/song/{requestId}	Poll a submitted song job

Request & Response

Request body

Name	Type	Required	Description
clipId	string	Yes	The TikTok clip / music id (this is the clipId, not a songId). Max 64 chars

Response body

Field	Type	Description
requestId	string	Opaque ID for this request. Keep it to poll GET /api/v1/tiktok/song/{requestId} later
clipId	string	Resolved TikTok clip id
status	string	queued | processing | success | not-found | blocked | timed-out | cancelled
coalesced	boolean	true if this request attached to an already-in-flight job for the same clip
cached	boolean	true if served from a fresh, previously-scraped result
result	object | null	The TikTok music_info JSON. null until the job resolves
finishReason	string | null	Present once the job reaches a terminal status

Responses come back 200 with a terminal result if the job resolves within the hold window. Otherwise 202 — poll GET /api/v1/tiktok/song/{requestId}, or resubmit the same target (it coalesces onto the still-in-flight job, at no extra charge).

cURL

curl -X POST "https://api.megomi.com/api/v1/tiktok/song" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"clipId": "7123456789012345678"}'

Node.js

const res = await fetch("https://api.megomi.com/api/v1/tiktok/song", {
  method: "POST",
  headers: {
    "x-api-key": process.env.MEGOMI_API_KEY,
    "content-type": "application/json",
  },
  body: JSON.stringify({ clipId: "7123456789012345678" }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.megomi.com/api/v1/tiktok/song",
    json={"clipId": "7123456789012345678"},
    headers={"x-api-key": "YOUR_API_KEY"},
)
print(res.json())

PHP

<?php
$ch = curl_init("https://api.megomi.com/api/v1/tiktok/song");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: YOUR_API_KEY", "content-type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(["clipId" => "7123456789012345678"]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);

Go

body, _ := json.Marshal(map[string]string{"clipId": "7123456789012345678"})
req, _ := http.NewRequest("POST", "https://api.megomi.com/api/v1/tiktok/song", bytes.NewReader(body))
req.Header.Set("x-api-key", "YOUR_API_KEY")
req.Header.Set("content-type", "application/json")
resp, _ := http.DefaultClient.Do(req)

200 · success

{
  "requestId": "req_9f1kQ3zP7mLxA2dR",
  "clipId": "7123456789012345678",
  "status": "success",
  "coalesced": false,
  "cached": false,
  "result": { "music_info": { "id": "7123...", "title": "Original Sound", "authorName": "creator" } },
  "finishReason": null
}

202 · queued

{
  "requestId": "req_7bN0wVh4TzKx9pQe",
  "clipId": "7123456789012345678",
  "status": "queued",
  "coalesced": false,
  "cached": false,
  "result": null
}

400

{ "status": 400, "title": "Bad Request", "detail": "clipId is required" }

401

{ "status": 401, "title": "Unauthorized", "detail": "invalid API key" }

402

{
  "status": 402,
  "title": "Payment Required",
  "detail": "insufficient credit balance",
  "required": 1,
  "balance": 0
}

403 · blocked

{
  "status": 403,
  "title": "Forbidden",
  "detail": "the source blocked this song lookup (age-gated, bot-checked, or otherwise inaccessible)",
  "requestId": "req_2wYh8LmN5vRtCx1s",
  "clipId": "7123456789012345678",
  "finishReason": "blocked"
}

Poll a submitted job

If your submit came back 202, fetch the result later with the requestId:

GET/api/v1/tiktok/song/{requestId}

Returns the current state of the request. A 404 means the requestId doesn’t belong to your key. A blocked job returns 403, same shape as the submit response above.

Field	Type	Description
requestId	string	The request you polled
clipId	string	Resolved TikTok clip id
status	string	Current job status
requestCount	number	How many times this job has been requested
result	object | null	The TikTok music_info JSON, null until resolved
finishReason	string | null	Present once terminal
createdAt	string	ISO-8601 timestamp
finishedAt	string | null	ISO-8601 timestamp, once terminal

cURL

curl "https://api.megomi.com/api/v1/tiktok/song/req_9f1kQ3zP7mLxA2dR" \
  -H "x-api-key: YOUR_API_KEY"

Node.js

const res = await fetch(
  "https://api.megomi.com/api/v1/tiktok/song/req_9f1kQ3zP7mLxA2dR",
  { headers: { "x-api-key": process.env.MEGOMI_API_KEY } },
);
const data = await res.json();