Developer integration

Xiaohongshu handoff API documentation

Three steps: prepare images, create a handoff and share the returned link. Successful responses have code 0; errors have code -1. Check both the HTTP status and the application code.

export NOTEHANDOFF_KEY="sk_REPLACE_WITH_YOUR_KEY"
export BASE="https://tudilink.com"

# Optional: upload your images one at a time and save each data.url
curl -sS -X POST "$BASE/api/assets" \
  -H "Authorization: Bearer $NOTEHANDOFF_KEY" \
  -F "file=@./cover.jpg"

# Create a handoff; preserve the content version and idempotency key for retries
curl -sS -X POST "$BASE/api/v1/handoffs" \
  -H "Authorization: Bearer $NOTEHANDOFF_KEY" \
  -H "Idempotency-Key: article-001:v1" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "A note, ready for your phone",
  "content": "This is a test note for trying the handoff flow. Check the images and text before deciding whether to publish.",
  "images": [
    "https://tudilink.com/demo/01.png",
    "https://tudilink.com/demo/02.png"
  ]
}'

# Share data.url from the creation response with the publisher

Authentication

Server requests include an API key in the request header. Full keys are shown once and stored as hashes. Replace and revoke a lost key.

Upload assets

POST /api/assets

Send multipart/form-data with exactly one file field. PNG, JPEG and static WebP signatures are checked; each file may be up to 10 MiB. The response includes dimensions and asset expiry.

Retain successful uploads and retry only failed files. The images array sets the preparation and transfer order; check the order again in the app.

Asset URLs at /m/:key are publicly readable for seven days after upload. Tall images retain their original dimensions; header checks do not guarantee decoding by every app.

Create a handoff

POST /api/v1/handoffs

Example creation response

New handoffs return HTTP 201; matching replays return HTTP 200. Some note fields are omitted here. Real IDs are UUIDs and tokens are 43-character base64url values.

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "00000000-0000-4000-8000-000000000000",
    "token": "<HANDOFF_TOKEN>",
    "url": "https://tudilink.com/p/<HANDOFF_TOKEN>",
    "status": "ready",
    "chargedCredits": 1,
    "replayed": false,
    "launchAttempts": 0,
    "editorReceivedAt": null,
    "publishedAt": null,
    "noteUrl": null,
    "confirmationSource": null
  }
}

Idempotency and billing

Creating a handoff consumes one credit in the same atomic operation as saving it. Idempotency applies to the same account, key and normalized content.

A network error, timeout or 5xx does not prove creation failed. Retry the original content with the original key to avoid duplicate charges.

List handoffs

GET /api/v1/handoffs

Use page and pageSize for pagination; the response contains items and total. Revoke notes or record receipt feedback and note links in the creator’s workspace.

curl -sS "$BASE/api/v1/handoffs?page=1&pageSize=30" \
  -H "Authorization: Bearer $NOTEHANDOFF_KEY"

Status meanings

Receipt and publication records are not verified by Xiaohongshu.

Error handling

Use the HTTP status, message and x-error-code together. Follow Retry-After when it is supplied.

Limits

• Titles: up to 20 equivalent characters. Text: up to 1,000 Unicode code points.
• Handoff input accepts 1–18 images; check actual editor receipt for the device, app version and content.
• Each image: up to 10 MiB, 32,768 pixels on either side and 80 million pixels total.
• Up to 100 uploads per account per day, plus site resource limits independent of purchased credits. Credits are required before upload; no credit is charged if no handoff is created.
• Hosted assets last up to seven days from upload. Handoffs last up to seven days and no later than their earliest hosted image. Reuse does not extend asset expiry.
• Image notes only. Users confirm final publication in Xiaohongshu.

Generic HTTP nodes

Tools such as Coze, n8n and Dify can use a generic HTTP node. Supply uploaded asset URLs or existing valid public HTTPS image URLs.

Do not use an execution ID that changes on every rerun as the idempotency key. Refer to each tool’s documentation for its node interface.