POST /b2b-songs/transfer — Video Transfer endpoint reference
Submit a music video for distribution: required files (video, thumbnail), required metadata (videoId, primaryArtist, label, isrc), example requests in cURL, JavaScript and Python, and the response codes.
This endpoint accepts one music video per request, together with its thumbnail and release metadata, and queues it for distribution processing. It is the only endpoint in v1 of the Video Transfer API.
Headers#
| Header | Value | Required |
|---|---|---|
x-api-key | Your partner API key | Yes |
Content-Type | multipart/form-data (set automatically by most HTTP clients when you attach files) | Yes |
Required files#
| Field | Type | Required | Description |
|---|---|---|---|
video | MP4 | Yes | The video file. Maximum 5 GB. No watermarks, logos or contact information. |
thumbnail | JPG / PNG | Yes | Preview image, 1280×720 or 1080p. |
Required metadata#
| Field | Type | Description |
|---|---|---|
videoId | string | Your (the partner’s) unique ID for the video. Used for de-duplication — resubmitting the same videoId returns 409 Conflict. |
primaryArtist | string[] | Array of primary artist names. Must be an array even for a single artist. |
label | string | Label name as it should appear on platforms. |
isrc | string | ISRC of the recording. See ISRC and UPC codes explained. |
[CONFIRM: optional metadata fields (title, releaseDate, explicit, genre, featuredArtist…) — the source documentation lists only the four required fields]
Validation: primaryArtist must be an array#
The most common 400 is sending the artist as a plain string.
// ✕ Invalid — rejected with 400
{ "primaryArtist": "Arafat" }
// ✓ Valid
{ "primaryArtist": ["Arafat"] }
In a multipart body, send the array either as a JSON-encoded string in the primaryArtist field, or as repeated primaryArtist[] fields. [CONFIRM: which array encoding the endpoint expects]
Example requests#
cURL#
curl -X POST "https://api.ansmusic.io/b2b-songs/transfer"
-H "x-api-key: $ANS_API_KEY"
-F "video=@/path/to/video.mp4;type=video/mp4"
-F "thumbnail=@/path/to/thumb.jpg;type=image/jpeg"
-F "videoId=PARTNER-000123"
-F 'primaryArtist=["Arafat"]'
-F "label=Example Records"
-F "isrc=QTXXX2612345"
JavaScript (Node 18+)#
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("video", await openAsBlob("./video.mp4"), "video.mp4");
form.append("thumbnail", await openAsBlob("./thumb.jpg"), "thumb.jpg");
form.append("videoId", "PARTNER-000123");
form.append("primaryArtist", JSON.stringify(["Arafat"]));
form.append("label", "Example Records");
form.append("isrc", "QTXXX2612345");
const res = await fetch("https://api.ansmusic.io/b2b-songs/transfer", {
method: "POST",
headers: { "x-api-key": process.env.ANS_API_KEY },
body: form,
});
if (res.status !== 201) {
console.error("Transfer failed", res.status, await res.text());
} else {
console.log("Created", await res.json());
}
Python (requests)#
import json, os, requests
resp = requests.post(
"https://api.ansmusic.io/b2b-songs/transfer",
headers={"x-api-key": os.environ["ANS_API_KEY"]},
files={
"video": ("video.mp4", open("video.mp4", "rb"), "video/mp4"),
"thumbnail": ("thumb.jpg", open("thumb.jpg", "rb"), "image/jpeg"),
},
data={
"videoId": "PARTNER-000123",
"primaryArtist": json.dumps(["Arafat"]),
"label": "Example Records",
"isrc": "QTXXX2612345",
},
timeout=600,
)
print(resp.status_code, resp.json())
Responses#
| Code | Status | Meaning |
|---|---|---|
| 201 | Created | Success — the video is queued for processing. |
| 400 | Validation | Invalid metadata — a required field is missing or malformed (e.g. primaryArtist not an array). |
| 401 | Unauthorized | Missing or invalid API key. |
| 409 | Conflict | Duplicate — this videoId (or ISRC) was already submitted. |
| 500 | Server | Internal error — retry with backoff; contact support if it persists. |
Example success response#
{
"status": "created",
"videoId": "PARTNER-000123",
"isrc": "QTXXX2612345"
}
[CONFIRM: exact response body schema for 201 and for error responses]
See also#
Thanks — your feedback helps us improve this article.
Still stuck?
Our support team answers tickets every business day. Include your account email and the release UPC or ISRC so we can jump straight in.