Appearance
Quickstart
Publish a video file from a terminal or from your own code, with the socialized.dev CLI, curl or Node.js. Each sample below does the whole job, from the file on your disk to a publication.
Before you start
Three things come from the dashboard at dash.socialized.dev:
- A connected account. Connecting uses OAuth, so it happens in a browser: connect a YouTube, Instagram or Facebook account on the Connections page. You publish by platform name: each target uses the brand’s connection for that platform.
- An API key, made on the Developer page. That page shows the samples below with your own key and brand already in them.
- Your brand’s ID (
brand_…), on the Developer page too, or fromsocialized.dev brands listandGET /brands(Brands). With a default brand stored (socialized.dev brands use), the CLI’s--brand-idis optional.
Publish a video
Each sample uploads ./clip.mp4 and publishes it to YouTube and Instagram. Put your key in place of sk_your_api_key and your brand’s ID in place of brand_your_brand_id, and list the platforms you connected.
# Uploads ./clip.mp4, then publishes it. Needs curl and jq.
set -euo pipefail
API=https://api.socialized.dev/api/v1
KEY=sk_your_api_key
FILE=./clip.mp4
# Plan the upload: one URL for each part of the file.
PLAN=$(curl -sf "$API/assets" \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d @- <<JSON
{ "filename": "clip.mp4", "contentType": "video/mp4", "sizeBytes": $(wc -c < "$FILE" | tr -d ' ') }
JSON
)
ASSET=$(jq -r .assetId <<< "$PLAN")
PART_SIZE=$(jq -r .partSize <<< "$PLAN")
# Send each part to its URL, keeping the ETag it answers with.
PARTS=$(jq -r '.parts[] | "\(.partNumber) \(.url)"' <<< "$PLAN" |
while read -r N URL; do
ETAG=$(dd if="$FILE" bs="$PART_SIZE" skip=$((N - 1)) count=1 2>/dev/null |
curl -sf -X PUT --data-binary @- -D - -o /dev/null "$URL" |
awk 'tolower($1) == "etag:" { print $2 }' | tr -d '\r')
jq -n --argjson partNumber "$N" --arg etag "$ETAG" '{ partNumber: $partNumber, etag: $etag }'
done | jq -s .)
# Complete the upload.
curl -sf "$API/assets/$ASSET/complete" -o /dev/null \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d @- <<JSON
{ "parts": $PARTS }
JSON
# Publish it. The Idempotency-Key makes a retry safe.
curl -sf "$API/brands/brand_your_brand_id/publications" \
-H "Authorization: Bearer $KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d @- <<JSON
{
"videoAssetId": "$ASSET",
"title": "My first video",
"targets": [
{ "platform": "youtube" },
{ "platform": "instagram" }
]
}
JSONimport { readFile } from 'node:fs/promises';
const api = 'https://api.socialized.dev/api/v1';
const post = async (path, body, headers = {}) => {
const response = await fetch(api + path, {
method: 'POST',
headers: {
Authorization: 'Bearer sk_your_api_key',
'Content-Type': 'application/json',
...headers,
},
body: JSON.stringify(body),
});
if (!response.ok) throw new Error(await response.text());
return response.json();
};
// Plan the upload: one URL for each part of the file.
const bytes = await readFile('./clip.mp4');
const plan = await post('/assets', {
filename: 'clip.mp4',
contentType: 'video/mp4',
sizeBytes: bytes.length,
});
// Send each part to its URL, keeping the ETag it answers with.
const parts = [];
for (const { partNumber, url } of plan.parts) {
const start = (partNumber - 1) * plan.partSize;
const body = bytes.subarray(start, start + plan.partSize);
const put = await fetch(url, { method: 'PUT', body });
if (!put.ok) throw new Error(`Part ${partNumber}: HTTP ${put.status}`);
parts.push({ partNumber, etag: put.headers.get('etag') });
}
// Complete the upload, then publish it. The Idempotency-Key makes a retry safe.
await post(`/assets/${plan.assetId}/complete`, { parts });
const publication = await post('/brands/brand_your_brand_id/publications',
{
videoAssetId: plan.assetId,
title: 'My first video',
targets: [{ platform: 'youtube' }, { platform: 'instagram' }],
},
{ 'Idempotency-Key': crypto.randomUUID() },
);
console.log(publication);npm install -g @socialized.dev/cli
socialized.dev login --key sk_your_api_key
# Uploads the file, then publishes it.
socialized.dev publications create \
--brand-id brand_your_brand_id \
--video ./clip.mp4 \
--title "My first video" \
--targets '[{ "platform": "youtube" }, { "platform": "instagram" }]'The CLI’s publications create uploads the file and publishes it in one command. With curl or Node.js you take its four steps yourself:
- Plan the upload.
POST /assetswith the file’s name, type and size answers with the video asset’sassetId, thepartSize(10 MiB) and one presignedPUTURL per part. - Send each part to its URL and keep the
ETagheader it answers with. The URLs are signed for thehostheader only, so a plainPUTwith the bytes and a normalContent-Lengthis enough (no chunked transfer encoding). AContent-Typeon a part is ignored: the asset’s type is thecontentTypeyou planned it with. - Complete the upload.
POST /assets/{assetId}/completewith each part’s number and ETag, quoted as the header arrives or not, records the asset, ready to publish. - Publish it.
POST /brands/{brandId}/publicationssends the asset to every target. TheIdempotency-Keymakes a retry safe (Idempotency).
The publish call answers with the publication and each target, in platform order:
The publish call’s response
{
"publicationId": "pub_…",
"status": "queued",
"targets": [
{
"id": "tgt_…",
"platform": "youtube",
"status": "pending",
"format": "short",
"formatChoice": "platform"
},
{
"id": "tgt_…",
"platform": "instagram",
"status": "pending",
"format": "reel",
"formatChoice": "platform"
}
]
}A custom cover is an image uploaded the same way, as its own asset (an image contentType, such as image/jpeg); send its assetId as coverAssetId. The CLI takes --cover ./cover.jpg.
Watch it go live
Each target travels pending → processing → published, and the publication settles to done, partial or failed. Read the brand’s publications back, or subscribe to a webhook instead of polling:
curl https://api.socialized.dev/api/v1/brands/brand_your_brand_id/publications \
-H "Authorization: Bearer sk_your_api_key"const response = await fetch(
'https://api.socialized.dev/api/v1/brands/brand_your_brand_id/publications',
{ headers: { Authorization: 'Bearer sk_your_api_key' } },
);
console.log(await response.json());npm install -g @socialized.dev/cli
socialized.dev login --key sk_your_api_key
socialized.dev publications list --brand-id brand_your_brand_idThe CLI follows one publication until it settles, reading it every 2 seconds:
CLI: follow one publication
socialized.dev publications get --id pub_… --watchWhen a target reaches published, its externalUrl is the live post.
That’s the whole loop: upload once, publish everywhere, watch it settle. Next: Authentication for keys and brands, Publishing a video for the full model, or the REST API reference for every endpoint.