Overview

SyncNode is a unified AI API gateway. Run AI tasks across multiple providers through a single endpoint — no separate integrations needed. Connect your provider keys once, and SyncNode handles routing, billing, file hosting, and result tracking.

Content Moderation

Moderate text & images in one call. Get safety scores instantly.

Chat Completions

GPT, Claude, Llama & 200+ models via OpenRouter or direct OpenAI.

Image & Video Generation

Any Replicate, FAL, Alibaba, or BytePlus model + auto CDN hosting.

Face Swap

Swap faces in images with a single API call.

Simple Billing

Pay-as-you-go. Auto-recharge when balance is low.

Auto File Hosting

Generated files auto-upload to your Bunny CDN or S3 bucket.

Base URLs

Service	Base URL
AI Tasks (Chat, Images, Face Swap)	`https://run.syncnode.ai`
Content Moderation	`https://moderate.syncnode.ai`

Quickstart

Get up and running in under 2 minutes.

Create an account — Sign up to get your API key and a $5.00 starting balance.
Add your provider API keys — Go to API Keys and add your OpenRouter, OpenAI, Replicate, FAL, Alibaba, or BytePlus key.
Make your first API call — Use the examples in the endpoint pages or the API Playground.
Check results — View task status and output on your Dashboard or poll the status endpoint.

Tip: The Moderation endpoint works out of the box — no provider keys needed. Try it first!

Authentication

All API requests require your SyncNode API key (sent as apiKey in the request body or query string). Some endpoints also require a Bearer token for additional authentication. Both are on your API Key page.

Field naming: SyncNode accepts the API key under any of three field names — apiKey (preferred, modern), api_key (snake_case alternative), or uid (legacy alias). Pick whichever fits your codebase; they all behave identically. These docs use apiKey for examples.

Authenticated Request

Include both apiKey in the body/query and a Bearer token in the header for protected endpoints.

cURL

curl -X POST https://run.syncnode.ai/chat-completion \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{"apiKey": "__API_KEY__"}'

Public Endpoints (API key only)

These only need your API key (sent as apiKey) — no Bearer token:

POST /chat-completion
POST /chatgpt-completion
POST /generate
POST /fal/generate · GET /fal/status
POST /alibaba/generate · GET /alibaba/status
POST /byteplus/generate · GET /byteplus/status · POST /byteplus/image · POST /byteplus/asset
POST /face-swap/run · GET /face-swap/status
GET /prediction-status
GET /balance
POST https://moderate.syncnode.ai

Pricing

Simple, per-call pricing. No subscriptions.

Endpoint	Cost per Call
Chat Completion (OpenRouter)	$0.02
ChatGPT Completion (OpenAI)	$0.02
Image / Video Generation (Replicate)	$0.02
Image / Video Generation (FAL)	$0.02
Image / Video Generation (Alibaba DashScope)	$0.02
Video Generation (BytePlus Seedance)	$0.02
Image Generation (BytePlus Seedream)	$0.02
Face Swap	$0.02
Content Moderation	$0.005

New accounts start with $5.00 free credits. Auto-recharge triggers when your balance drops below $0.01 (configurable threshold, default $50).

Content Moderation

Moderate text and images in a single request. Returns granular safety scores for harassment, hate, violence, sexual content, self-harm, and more — plus a simple safe flag. No provider API keys needed.

POST https://moderate.syncnode.ai $0.005 / call

Request Parameters

Parameter	Type	Required	Description
apiKey	string	required	Your SyncNode API key (from /api_keys)
text	string	optional	Text content to moderate
imageUrl	string	optional	URL of image to moderate
imageBase64	string	optional	Base64-encoded image data
imageMime	string	optional	MIME type when using imageBase64 (e.g. `image/png`)

At least one of text, imageUrl, or imageBase64 must be provided. You can combine text + image in a single call.

Text + Image Moderation

cURL

curl -X POST "https://moderate.syncnode.ai" \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "text": "Hello, this is a test message",
  "imageUrl": "https://example.com/photo.jpg"
}'

JavaScript

const response = await fetch("https://moderate.syncnode.ai", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    apiKey: "__API_KEY__",
    text: "Hello, this is a test message",
    imageUrl: "https://example.com/photo.jpg"
  })
});

const result = await response.json();
console.log(result.overall_moderation.safe); // 1 = safe, 0 = flagged

Python

import requests

response = requests.post("https://moderate.syncnode.ai", json={
    "apiKey": "__API_KEY__",
    "text": "Hello, this is a test message",
    "imageUrl": "https://example.com/photo.jpg"
})

result = response.json()
print(result["overall_moderation"]["safe"])  # 1 = safe, 0 = flagged

Response

JSON Response

{
  "apiKey": "__API_KEY__",
  "text_moderation": {
    "scores": {
      "harassment": 0.00004,
      "harassment/threatening": 0.000007,
      "sexual": 0.003,
      "hate": 0.00001,
      "hate/threatening": 0.0000005,
      "illicit": 0.00001,
      "illicit/violent": 0.000009,
      "self-harm/intent": 0.000002,
      "self-harm/instructions": 0.000001,
      "self-harm": 0.000006,
      "sexual/minors": 0.00002,
      "violence": 0.0005,
      "violence/graphic": 0.000009
    },
    "nudity": 0, "underage": 0, "vulgar": 0, "safe": 1
  },
  "image_moderation": {
    "scores": { "harassment": 0, "sexual": 0.00007, "violence": 0.023, "self-harm": 0.004 },
    "nudity": 0, "underage": 0, "vulgar": 0, "safe": 1
  },
  "overall_moderation": { "nudity": 0, "underage": 0, "vulgar": 0, "safe": 1 }
}

Response Fields

Field	Description
text_moderation	Present when `text` was provided. Contains per-category scores and flags.
image_moderation	Present when an image was provided. Contains per-category scores and flags.
overall_moderation	Combined result across all inputs.
safe	1 = content is safe, 0 = content was flagged.
nudity / underage / vulgar	0 or 1 — specific content flags.
scores	Granular 0–1 scores for each moderation category (lower = safer).

Text Only

cURL

curl -X POST "https://moderate.syncnode.ai" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "__API_KEY__", "text": "Check if this text is safe"}'

Image Only (URL)

cURL

curl -X POST "https://moderate.syncnode.ai" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "__API_KEY__", "imageUrl": "https://example.com/image.jpg"}'

Image Only (Base64)

cURL

curl -X POST "https://moderate.syncnode.ai" \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "imageBase64": "iVBORw0KGgoAAAANS...",
  "imageMime": "image/png"
}'

Best Practice: Always check overall_moderation.safe first. If 0, inspect scores to see which categories were flagged.

Chat Completion (OpenRouter)

Send chat messages to 200+ AI models via OpenRouter. Requires an OpenRouter API key in your API Keys settings.

POST https://run.syncnode.ai/chat-completion $0.02 / call

Request Parameters

Parameter	Type	Required	Description
apiKey	string	required	Your SyncNode API key (from /api_keys)
model	string	required	Model ID (e.g. `openai/gpt-4o`, `anthropic/claude-3.5-sonnet`)
messages	array	required	Array of `{role, content}` message objects
prompt	string	optional	Alternative to messages for simple single prompts
max_tokens	number	optional	Maximum tokens in response
temperature	number	optional	Sampling temperature (0–2)

cURL

curl -X POST https://run.syncnode.ai/chat-completion \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "model": "openai/gpt-4o",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Explain quantum computing in 3 sentences."}
  ],
  "max_tokens": 500,
  "temperature": 0.7
}'

JavaScript

const response = await fetch("https://run.syncnode.ai/chat-completion", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    apiKey: "__API_KEY__",
    model: "openai/gpt-4o",
    messages: [
      { role: "system", content: "You are a helpful assistant." },
      { role: "user", content: "Explain quantum computing in 3 sentences." }
    ],
    max_tokens: 500,
    temperature: 0.7
  })
});
const data = await response.json();
console.log(data.prediction.output.choices[0].message.content);

Python

import requests

response = requests.post("https://run.syncnode.ai/chat-completion", json={
    "apiKey": "__API_KEY__",
    "model": "openai/gpt-4o",
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing in 3 sentences."}
    ],
    "max_tokens": 500,
    "temperature": 0.7
})
data = response.json()
print(data["prediction"]["output"]["choices"][0]["message"]["content"])

Response

JSON Response

{
  "prediction": {
    "id": 123,
    "apiKey": "__API_KEY__",
    "output": {
      "model": "openai/gpt-4o",
      "choices": [{
        "index": 0,
        "message": { "role": "assistant", "content": "Quantum computing uses qubits..." },
        "finish_reason": "stop"
      }],
      "usage": { "prompt_tokens": 25, "completion_tokens": 85, "total_tokens": 110 }
    },
    "cost": 0.02, "model": "openai/gpt-4o", "status": "completed",
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

ChatGPT Completion (Direct OpenAI)

Send requests directly to the OpenAI API. Requires an OpenAI API key stored in your API Keys.

POST https://run.syncnode.ai/chatgpt-completion $0.02 / call

cURL

curl -X POST https://run.syncnode.ai/chatgpt-completion \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "model": "gpt-4o",
  "messages": [
    {"role": "user", "content": "Write a haiku about programming."}
  ],
  "max_tokens": 100,
  "temperature": 0.8
}'

Difference: /chat-completion routes through OpenRouter (200+ models). /chatgpt-completion goes directly to OpenAI using your OpenAI key.

Image, Video & Audio Generation via Replicate

Generate images, videos, and audio using any Replicate model. Results auto-upload to your configured CDN host. Requires a Replicate API key saved under Provider Credentials.

POST https://run.syncnode.ai/generate $0.02 / call

Request Parameters

Parameter	Type	Required	Description
apiKey	string	required	Your SyncNode API key (from /api_keys)
model	string	required	Replicate model ID (e.g. `stability-ai/sdxl` or full version hash)
input	object	required	Model-specific input parameters

Generate an Image (Flux Schnell — fast)

cURL

curl -X POST https://run.syncnode.ai/generate \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "model": "black-forest-labs/flux-schnell",
  "input": {
    "prompt": "A serene mountain landscape at sunset, photorealistic",
    "aspect_ratio": "16:9",
    "num_outputs": 1,
    "output_format": "webp"
  }
}'

Generate an Image (RealVisXL — higher quality)

cURL

curl -X POST https://run.syncnode.ai/generate \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "model": "adirik/realvisxl-v3.0-turbo:3dc73c80...",
  "input": {
    "width": 768, "height": 768,
    "prompt": "A serene mountain landscape at sunset, photorealistic",
    "negative_prompt": "low quality, blurry, sketch",
    "num_outputs": 1, "guidance_scale": 7, "num_inference_steps": 25
  }
}'

Generate a Video

cURL

curl -X POST https://run.syncnode.ai/generate \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "model": "bytedance/seedance-1-lite",
  "input": {
    "fps": 24, "prompt": "A woman walks through a sunlit park",
    "duration": 5, "resolution": "720p", "aspect_ratio": "16:9"
  }
}'

Response (Job Created)

JSON

{
  "success": true,
  "job_id": "b6nqrw6zbdrmc0cqwqbr8b3dm8",
  "get": "https://run.syncnode.ai/prediction-status?job_id=b6nqrw6zbdrmc0cqwqbr8b3dm8",
  "status": "in_progress"
}

Image/video generation is async. Use the get URL or the Prediction Status endpoint to poll for results.

Image, Video & Audio Generation via FAL

Run any model from fal.ai through SyncNode — images, video, audio, multimodal. Submission is queued and SyncNode polls FAL until the job completes, then uploads the result to your CDN. Requires a FAL API key saved under Provider Credentials.

POST https://run.syncnode.ai/fal/generate $0.02 / call

Request Parameters

Parameter	Type	Required	Description
apiKey	string	required	Your SyncNode API key (from /api_keys)
model	string	required	Full FAL model path (e.g. `fal-ai/recraft/v4.1/text-to-image`, `fal-ai/flux/dev`). The model is part of the URL on FAL's side.
input	object	required	Model-specific input (e.g. `prompt`, `image_size`, `enable_safety_checker`). Forwarded directly to FAL.

Generate an Image

cURL

curl -X POST https://run.syncnode.ai/fal/generate \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "model": "fal-ai/recraft/v4.1/text-to-image",
  "input": {
    "prompt": "Tilt-shift miniature of a Portuguese fishing village at golden hour",
    "image_size": "landscape_16_9",
    "enable_safety_checker": true
  }
}'

Response (Job Created)

JSON

{
  "success": true,
  "job_id": "eff9450f-84e5-4aeb-86e8-3ec1a197c033",
  "provider_job_id": "019e314d-ed5f-70d1-8781-20ac1eb39f06",
  "task_status": "IN_QUEUE",
  "status": "in_progress"
}

Poll Status

GET https://run.syncnode.ai/fal/status?job_id={job_id}

cURL

curl "https://run.syncnode.ai/fal/status?job_id=eff9450f-84e5-4aeb-86e8-3ec1a197c033"

Task Status Values

Status	Description
`IN_QUEUE`	Submitted, waiting to start
`IN_PROGRESS`	Model is running
`COMPLETED`	Done — `output` contains the final URL (uploaded to your CDN host if configured)
`FAILED`	Failed — check `output` for the error message

SyncNode also polls FAL every 60 seconds via a background cron, so completion happens even if you never call /fal/status. Manual polling just makes it faster.

Image, Video & Audio Generation via Alibaba DashScope

Run Wan family models (image, video, multimodal) from Alibaba DashScope through SyncNode. Image and multimodal generation can be synchronous; video generation is always async. Requires an Alibaba DashScope API key saved under Provider Credentials.

POST https://run.syncnode.ai/alibaba/generate $0.02 / call

Request Parameters

Parameter	Type	Required	Description
apiKey	string	required	Your SyncNode API key (from /api_keys)
model	string	required	DashScope model name (e.g. `wan2.7-image-pro`, `wan2.7-i2v`)
input	object	required	DashScope input. For multimodal: `{ messages: [...] }`. For video: `{ prompt, media: [...] }`.
parameters	object	optional	Model-specific knobs: `size`, `resolution`, `duration`, `n`, `watermark`, `prompt_extend`, etc.
endpoint	string	optional	Override the DashScope endpoint path. Defaults are inferred from model name.

Generate an Image (Wan Image Pro)

cURL

curl -X POST https://run.syncnode.ai/alibaba/generate \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "model": "wan2.7-image-pro",
  "input": {
    "messages": [{
      "role": "user",
      "content": [{ "text": "A futuristic cyberpunk city at night, neon lights, rain" }]
    }]
  },
  "parameters": { "size": "2K", "n": 1, "watermark": false }
}'

Generate a Video (Wan i2v)

cURL

curl -X POST https://run.syncnode.ai/alibaba/generate \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "model": "wan2.7-i2v",
  "input": {
    "prompt": "A cat surfing on a wave",
    "media": [
      { "type": "first_frame", "url": "https://example.com/first.jpg" }
    ]
  },
  "parameters": { "resolution": "1080P", "duration": 5, "prompt_extend": true }
}'

Response (Async Job)

JSON

{
  "success": true,
  "job_id": "a3c8...",
  "provider_job_id": "ds-task-abc...",
  "task_status": "PENDING",
  "status": "in_progress"
}

Poll Status

GET https://run.syncnode.ai/alibaba/status?job_id={job_id}

cURL

curl "https://run.syncnode.ai/alibaba/status?job_id=a3c8..."

Task Status Values

Status	Description
`PENDING` / `QUEUED`	Submitted, waiting to start
`RUNNING`	Model is running
`SUCCEEDED`	Done — `output` contains the final URL (uploaded to your CDN host if configured)
`FAILED` / `CANCELED`	Failed — check `output` for the error message

Video models on DashScope can take several minutes. SyncNode polls every 60 seconds in the background, so the prediction row finalizes automatically even without manual polling.

Video input quirk: For i2v models, SyncNode automatically re-uploads your image URLs to DashScope OSS first (DashScope's backend can't reliably fetch external CDN URLs). You don't need to do anything — just pass an https://... URL.

Image, Video & Audio Generation via BytePlus (Ark)

Run Dreamina / Seedance models through BytePlus Ark. Generation is async — submit a task, then poll until it completes. Results auto-upload to your configured CDN host. Requires a BytePlus API key (an ark-... key) saved under Provider Credentials.

POST https://run.syncnode.ai/byteplus/generate $0.02 / call

Request Parameters

Parameter	Type	Required	Description
apiKey	string	required	Your SyncNode API key (from /api_keys)
model	string	required	Ark model ID (e.g. `dreamina-seedance-2-0-260128`)
content	array	required	Content parts, e.g. `[{ "type": "text", "text": "..." }]`
resolution	string	optional	e.g. `720p`, `1080p`
ratio	string	optional	Aspect ratio, e.g. `16:9`
duration	number	optional	Video length in seconds
watermark	boolean	optional	Whether to watermark output

Any additional fields are forwarded to Ark unchanged, so model-specific options work without SyncNode updates.

Generate a Video (Seedance 2.0)

cURL

curl -X POST https://run.syncnode.ai/byteplus/generate \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "model": "dreamina-seedance-2-0-260128",
  "content": [
    { "type": "text", "text": "A cat playing in a sunny garden" }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 5,
  "watermark": false
}'

Response (Job Created)

JSON

{
  "success": true,
  "job_id": "1f4a...",
  "provider_job_id": "cgt-20260716072325-5897s",
  "task_status": "running",
  "status": "in_progress"
}

Poll Status

GET https://run.syncnode.ai/byteplus/status?job_id={job_id}

cURL

curl "https://run.syncnode.ai/byteplus/status?job_id=1f4a..."

Task Status Values

Status	Description
`queued` / `running`	Task is processing (video gen typically takes 2–4 minutes)
`succeeded`	Done — `output` contains the final URL (uploaded to your CDN host if configured)
`failed` / `cancelled`	Failed — check `output` for the error message

SyncNode polls BytePlus every 60 seconds via a background cron, so tasks finalize even if you never call /byteplus/status. Manual polling just makes it faster.

Expiring URLs: BytePlus returns signed URLs that expire after 24 hours. SyncNode automatically re-uploads the output to your configured CDN host so your links don't die — configure a host under Hosting to benefit.

Image Generation (Seedream) — synchronous

Seedream image models use a separate synchronous endpoint — the response contains the image directly (no polling). SyncNode charges, re-hosts the image to your CDN, and returns it in one call.

POST https://run.syncnode.ai/byteplus/image $0.02 / call

cURL

curl -X POST https://run.syncnode.ai/byteplus/image \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "model": "dola-seedream-5-0-pro-260628",
  "prompt": "A red vintage bicycle leaning on a white wall, golden hour",
  "size": "2K",
  "response_format": "url",
  "watermark": false
}'
# → { "success": true, "job_id": "...", "status": "completed", "output": "https://your-cdn/..." }

Uses the same BytePlus (Ark) key as video. Any extra fields (e.g. n, seed) are forwarded to BytePlus unchanged. Request n>1 and output comes back as an array of URLs.

Heavy combos can time out. Because image generation is synchronous on BytePlus's side, very heavy model + size combinations (e.g. a Pro model at 4K) can exceed BytePlus's ~100s request limit and return HTTP 524. Keep sizes reasonable (1K/2K) or retry; SyncNode surfaces the timeout as an error rather than hanging.

BytePlus Asset Library real-person video

Seedance blocks raw photos of real people. To animate an actual person, first upload their photo to your BytePlus Virtual Avatar / Real-Human Portrait Library to get an asset:// ID, then reference that ID when generating. SyncNode proxies the (AK/SK-signed) library APIs so you never call BytePlus directly.

POST https://run.syncnode.ai/byteplus/asset no charge

Requires BytePlus AK/SK. The library APIs use Access Key signing (not the ark-… generation key). Add your Access Key + Secret Access Key under Provider Credentials → BytePlus Asset Library (AK:SK). You also need BytePlus Advanced Creation Rights activated on your account.

Request Shape

Parameter	Type	Required	Description
apiKey	string	required	Your SyncNode API key
action	string	required	Asset Library Action (see list below)
params	object	required	The Action's request body, passed to BytePlus verbatim

Actions: CreateAssetGroup, CreateAsset, GetAsset, GetAssetGroup, ListAssets, ListAssetGroups, UpdateAsset, UpdateAssetGroup, DeleteAsset, DeleteAssetGroup. The Real-Human Portrait Library uses the same route (set its GroupType in params).

Step 1 — Create an asset group

cURL

curl -X POST https://run.syncnode.ai/byteplus/asset \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "action": "CreateAssetGroup",
  "params": { "Name": "person_jane", "ProjectName": "default" }
}'
# → { "Result": { "Id": "group-..." } }

Step 2 — Upload the person's photo (async)

cURL

curl -X POST https://run.syncnode.ai/byteplus/asset \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "action": "CreateAsset",
  "params": {
    "GroupId": "group-...",
    "URL": "https://your-cdn.com/jane-photo.jpg",
    "AssetType": "Image",
    "ProjectName": "default"
  }
}'
# → { "Result": { "Id": "asset-..." } }

Photo rules (else Status: Failed): jpeg/png/webp/bmp/tiff/gif/heic, aspect ratio 0.4–2.5, 300–6000 px, <30 MB, clear frontal face. AssetType can be Image, Video, or Audio.

Step 3 — Poll until Active

cURL

curl -X POST https://run.syncnode.ai/byteplus/asset \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "action": "GetAsset",
  "params": { "Id": "asset-...", "ProjectName": "default" }
}'

`Result.Status`	Meaning
`Processing`	Still preprocessing — keep polling
`Active`	Ready — the asset ID can be used for generation
`Failed`	Rejected (photo didn't meet requirements)

Step 4 — Generate video referencing the asset

Use the existing /byteplus/generate endpoint. Put asset://<asset-id> in content[].image_url.url with role: "reference_image", and refer to it positionally in the prompt ("Image 1") — never by ID.

cURL

curl -X POST https://run.syncnode.ai/byteplus/generate \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "model": "dreamina-seedance-2-0-260128",
  "content": [
    { "type": "text", "text": "The person in Image 1 waves and smiles in a sunlit park" },
    { "type": "image_url", "role": "reference_image", "image_url": { "url": "asset://asset-..." } }
  ],
  "ratio": "16:9", "duration": 5, "watermark": false
}'
# → { "job_id": "..." }  then poll GET /byteplus/status?job_id=...  → CDN-hosted video

ProjectName must match between upload and generation (default "default") — a mismatch causes "asset not found." Asset-library calls are not billed by SyncNode; generation is $0.02 as usual.

Face Swap

Swap faces between two images. Provide source and target as base64-encoded strings.

POST https://run.syncnode.ai/face-swap/run $0.02 / call

Request Parameters

Parameter	Type	Required	Description
apiKey	string	required	Your SyncNode API key (from /api_keys)
input.source_image	string	required	Base64 source face image
input.target_image	string	required	Base64 target image
input.background_enhance	boolean	optional	Enhance background quality

cURL

curl -X POST https://run.syncnode.ai/face-swap/run \
  -H "Content-Type: application/json" \
  -d '{
  "apiKey": "__API_KEY__",
  "input": {
    "source_image": "BASE64_SOURCE_FACE...",
    "target_image": "BASE64_TARGET_IMAGE...",
    "background_enhance": true
  }
}'

Face swap is async. Poll /face-swap/status?job_id=... for the result.

Prediction Status

Poll for results of async jobs (image generation, face swap).

GET https://run.syncnode.ai/prediction-status?job_id={job_id}

cURL

curl "https://run.syncnode.ai/prediction-status?job_id=b6nqrw6zbdrmc0cqwqbr8b3dm8"

Response (Completed)

JSON

{
  "job_id": "b6nqrw6zbdrmc0cqwqbr8b3dm8",
  "replicate_status": "completed",
  "output": "https://your-cdn.b-cdn.net/gen_abc123_1752140031948.png",
  "updated": true
}

Status Values

Status	Description
`in_progress`	Job is still processing
`completed`	Done — `output` contains the result URL
`failed`	Failed — check `error` field

Polling: We recommend every 2–5 seconds until status changes from in_progress.

Balance

Check your current credit balance.

GET https://run.syncnode.ai/balance?apiKey={apiKey}

cURL

curl "https://run.syncnode.ai/balance?apiKey=__API_KEY__"

JSON Response

{"balance": 4.96}

API Keys

Manage your provider API keys. Stored securely and used to authenticate to providers on your behalf.

GET https://run.syncnode.ai/api-keys?apiKey={apiKey}

JSON Response

{
  "replicate_key": "r8_abc...",
  "chatgpt_key": "sk-abc...",
  "huggingface_key": "hf_abc...",
  "openrouter_key": "sk-or-v1-abc...",
  "alibaba_key": "sk-abc...",
  "fal_key": "abc123:def456...",
  "byteplus_key": "ark-abc..."
}

POST https://run.syncnode.ai/api-keys

cURL

curl -X POST https://run.syncnode.ai/api-keys \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"apiKey": "__API_KEY__", "openrouter_key": "sk-or-v1-your-key-here"}'

Supported Providers

Key Name	Provider	Used By
`openrouter_key`	OpenRouter	`/chat-completion`
`chatgpt_key`	OpenAI	`/chatgpt-completion`
`replicate_key`	Replicate	`/generate`
`fal_key`	FAL	`/fal/generate`
`alibaba_key`	Alibaba Cloud (DashScope)	`/alibaba/generate`
`byteplus_key`	BytePlus (Ark)	`/byteplus/generate`
`byteplus_aksk`	BytePlus Asset Library (AK:SK)	`/byteplus/asset`
`huggingface_key`	Hugging Face	Usage tracking

Tasks

List, view, and manage your task history.

GET https://run.syncnode.ai/tasks?apiKey={apiKey}&page=1&size=10

JSON Response

{
  "tasks": [{
    "id": 1, "job_id": "abc-123", "model": "openai/gpt-4o",
    "prompt": "Explain AI", "status": "completed", "cost": 0.02,
    "created_at": "2025-07-08T10:00:00Z"
  }],
  "page": 1, "size": 10, "total": 42
}

GET https://run.syncnode.ai/tasks/{id}?apiKey={apiKey} View single task

DELETE https://run.syncnode.ai/tasks/{id} Delete a task

Billing

View billing history, set auto-recharge thresholds, and manage payment methods.

Endpoint	Method	Description
`/billing-history?apiKey={apiKey}`	GET	Get charge history
`/billing-threshold?apiKey={apiKey}`	GET	Get auto-recharge threshold
`/billing-threshold`	POST	Set auto-recharge threshold
`/card?apiKey={apiKey}`	GET	View saved payment card
`/topup_card`	POST	Top up balance

Auto-Recharge: When balance drops below $0.01, SyncNode charges your saved card for the threshold amount (default $50). Change this in Billing settings.

API Playground

Test endpoints directly from this page. Your API key is auto-filled when signed in.

Claude Code Skill

Use SyncNode from inside Claude Code with a single install. The official SyncNode skill teaches Claude every endpoint, the auth flow, polling lifecycle, and pricing — so you can scaffold integrations by describing what you want instead of reading docs.

What it does

When you ask Claude Code something like "add image generation to my app via SyncNode" or "use SyncNode to wire up chat completions", the skill loads automatically and gives Claude:

The full endpoint surface (/generate, /chat-completion, /fal/generate, /alibaba/generate, /byteplus/generate, /face-swap/run, /moderate)
Auth pattern (API key + Bearer JWT)
Polling lifecycle for async jobs
Cost-per-call so it can warn before burning your balance
Working code samples in cURL, JavaScript, and Python
Common errors and how to fix them

Install

Option 1 — Global (recommended)

Clone into your user-level skills directory and it's available in every project:

bash

git clone https://github.com/syncnode-ai/claude-skill.git ~/.claude/skills/syncnode

Restart Claude Code. The skill auto-loads when its trigger description matches your prompt.

Option 2 — Per-project

Drop the SKILL.md (and examples/) into .claude/skills/syncnode/ inside your project. Anyone using Claude Code in that repo gets it.

Verify it's loaded

In Claude Code, type /skills — syncnode should appear in the list. Then try:

prompt

Set me up to use SyncNode for image generation

Claude should walk you through getting an API key, adding a Replicate provider credential, and scaffolding a working /generate call.

Repository

Source, examples, and contribution guidelines live on GitHub:

github.com/syncnode-ai/claude-skill

Direct link to the skill definition: SKILL.md

Tip: The skill includes a waitForCompletion() helper in both the JS and Python clients so you don't have to write polling loops for async jobs.

Error Codes

Standard HTTP error codes returned by the API.

Code	Meaning
`200`	Success
`400`	Bad request — missing or invalid parameters
`401`	Unauthorized — invalid or missing token
`402`	Payment required — insufficient balance, no card on file
`404`	Not found
`500`	Server error

Error Response Format

JSON

{"error": "Missing API key"}