Skip to content
Help Center
Log in Submit a ticket
Partner API

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.

POST /b2b-songs/transfer

Headers#

HeaderValueRequired
x-api-keyYour partner API keyYes
Content-Typemultipart/form-data (set automatically by most HTTP clients when you attach files)Yes

Required files#

FieldTypeRequiredDescription
videoMP4YesThe video file. Maximum 5 GB. No watermarks, logos or contact information.
thumbnailJPG / PNGYesPreview image, 1280×720 or 1080p.

Required metadata#

FieldTypeDescription
videoIdstringYour (the partner’s) unique ID for the video. Used for de-duplication — resubmitting the same videoId returns 409 Conflict.
primaryArtiststring[]Array of primary artist names. Must be an array even for a single artist.
labelstringLabel name as it should appear on platforms.
isrcstringISRC 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#

CodeStatusMeaning
201CreatedSuccess — the video is queued for processing.
400ValidationInvalid metadata — a required field is missing or malformed (e.g. primaryArtist not an array).
401UnauthorizedMissing or invalid API key.
409ConflictDuplicate — this videoId (or ISRC) was already submitted.
500ServerInternal 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#

Was this article helpful?

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.