接口参考

創作者目錄與 placements

訪客讀取與受保護的參與者操作分開。以下路徑相對於 https://api.vibevo.io/api/v1。

訪客目錄

GET /creator-catalog 接受 q、channelType（STREAMER 或 SOCIAL）、platform、format、topic、language、geo、audienceGeo、minPriceCents、maxPriceCents、availability、sort（price、relevance、activity）、limit（1–100）與 cursor。audienceGeo 是最新有效且已驗證受眾分布中占比大於零的 ISO 國家代碼；小寫輸入會正規化為大寫。舊有 geo 篩選仍代表創作者個人資料標籤。platform 與 audienceGeo 必須符合同一個啟用且已發布的服務頻道。price 排序及 cursor 依創作者最低已發布服務價格計算，可能不同於篩選後顯示的服務。唯一接受的 availability 值為 AVAILABLE；篩選依據是已發布服務。下單日期與「另行協商」不是可用狀態篩選。

curl 'https://api.vibevo.io/api/v1/creator-catalog?channelType=STREAMER&availability=AVAILABLE&limit=20'

# Anonymous response (public fields only)
{
  "data": [{
    "publicId": "d8e805e4-1ec5-4ab6-a734-4ea389cecc6c",
    "metricsObservationId": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "lastModified": "2026-10-08T12:00:00.000Z",
    "displayName": "Streamer One",
    "topics": ["gaming"],
    "languages": ["en"],
    "channelType": "STREAMER",
    "channels": [{"platform":"TWITCH","handle":"streamer_one","canonicalUrl":"https://www.twitch.tv/streamer_one"}],
    "services": [{
      "serviceListingId": 7, "type": "STREAM", "variant": "MENTION",
      "channel":{"platform":"TWITCH","handle":"streamer_one","canonicalUrl":"https://www.twitch.tv/streamer_one"},
      "proofModes":["PUBLIC_VOD"],
      "title": "Product mention", "unit": "broadcast",
      "basePrice": {"raw":"100000000","currency":"USDT","decimals":6},
      "packageOptions": [{"quantity":1,"discountBps":0,"packageBase":{"raw":"100000000","currency":"USDT","decimals":6}},{"quantity":5,"discountBps":500,"packageBase":{"raw":"475000000","currency":"USDT","decimals":6}}]
    }],
    "metrics": []
  }],
  "nextCursor": null
}

GET /creator-pages/{publicId} 會在創作者已發布頁面且仍有可用服務與使用條件時回傳；否則以 RESOURCE_NOT_FOUND 代碼回覆 404。個人資料、價格、服務或手動連結不需要預先審核。草稿、聯絡方式、證明檔案、私人排程與手續費欄位不會回傳。取消發布會撤銷頁面、HTML、Open Graph、快取與 sitemap 項目；未發布頁面不會被索引。

公開回應與價格

目錄顯示服務已發布的基本價格，不包含手續費或創作者收入。Money 格式為 {raw, currency: "USDT", decimals: 6}；raw 是 USDT 微單位整數。例如 raw "100000000" 代表 100 USDT。請求中的 priceCents 是整數分字串；USDT 輸入欄最多兩位小數。

已連接且驗證的社群帳號，其 channels[].audience 可包含該帳號已驗證的受眾地區、年齡及性別：source、capturedAt、verifiedAt、periodDays、geo 與 demo。平均觀看量使用最近五則公開貼文中已知且非負的觀看數。手動頻道沒有可信的受眾指標；缺少資料時顯示無資料，不會編造零值。

受保護的參與者流程

以下路徑皆有 /public 前綴且需要 API 金鑰：GET 需要 read；寫入需要 write 及目前角色與物件權限。

• 創作者：GET/PATCH /public/influencer-profile；GET /public/influencer-profile/page；POST /public/influencer-profile/page/generate、/submit、/page/publish 與 /page/unpublish；GET/POST /public/influencer-channels；GET/PUT /public/influencer-channels/{id}/pricing；POST /public/influencer-channels/{id}/ownership-challenge、/ownership-uploads、/ownership-uploads/{uploadId}/complete、/ownership-evidence 與 /submit。個人資料、頁面、頻道、ownership 與 pricing 也有 /api/v1 下不帶 /public 的 JWT 路徑。GET/PUT /public/influencer-accounts/{accountId}/pricing 保留為本人已啟用且驗證社群帳號的相容 alias；channel pricing 為正式路徑。相容欄位 publishAfterApproval 為 boolean：true 會立即發布目前版本且無須預先審核；false 僅建立私人預覽。手動頻道接受任何允許平台的安全公開 HTTPS URL；仍支援舊有的 Twitch／Kick handle-only 請求。所有權驗證為可選，不會阻止發布或購買。原生帳號仍須有效、已驗證、屬於創作者本人，且未封鎖、暫停、出售或刪除。JWT 專用 POST /api/v1/creator/social-accounts/{id}/avatar/refresh 更新本人帳號頭像，無須新增 OAuth，body 不接受來源 URL。Owner DTO 可選擇包含 socialAccountId 與 avatarUrl；不新增 MCP 頭像工具。
• 廣告主：POST /public/placement-orders 建立草稿；PATCH /public/placement-orders/{id} 修改；POST /public/placement-orders/{id}/quote 計價；POST /public/placement-orders/{id}/checkout 確認預留資金。自訂條件使用 POST /public/placement-offers/quote 和 POST /public/placement-offers。可用 GET /public/placement-orders、GET /public/placement-orders/{id}、GET /public/analytics/placements 與 GET /public/placement-orders/{id}/analytics 讀取訂單與分析。
• 資金到位後，訂單雙方可使用 GET /public/placement-assignments、GET /public/placement-assignments/{id}、/events 與 /deliverables；操作包括 accept、decline、submit、approve、request-changes、cancel、issues 與 change-proposals（提議／接受新期限）。使用 PUT /public/placement-assignments/{id}/deliverables/{deliverableId} 更新結果；私人上傳支援 create/complete 與已附加結果下載。JWT 對應路徑位於 /api/v1，沒有 /public。Staff 使用獨立 JWT 審核路徑。

若發布功能暫時關閉，明確的發布請求會保存意圖並回傳 503 WRITE_NOT_AVAILABLE_FOR_FEATURE。控制項重新開啟後，請使用相同 UUID Idempotency-Key 重試。這不會建立 staff 審核；已發布頁面仍可讀取，unpublish 仍可使用。

建立訂單

curl -X POST 'https://api.vibevo.io/api/v1/public/placement-orders' \
  -H "Authorization: Bearer $VIBEVO_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7ddc2979-9a7f-4d4f-8f89-38ea3353e444' \
  -d '{"items":[{"serviceListingId":7,"quantity":1,"discountBps":0,"dueAt":"2026-10-20T18:00:00.000Z","brief":"Mention the product during the broadcast.","results":[{"expectedAt":"2026-10-20T17:00:00.000Z"}],"rights":{}}]}'

results 項目數必須與選擇的刊登數（1、5 或 10）完全相同；expectedAt 是各次發布日期，dueAt 是整體期限。rights 包含雙方同意的使用條款。

Quote 與確認

POST /api/v1/public/placement-orders/{id}/quote
Idempotency-Key: <stable UUID>
{ "expectedVersion": 1 }

# Advertiser-safe quote projection
{
  "data": {
    "quoteId": "9e955328-7a2b-42a4-9963-330fcc83ad92",
    "quoteVersion": 1, "orderId": 14,
    "expiresAt": "2026-10-08T12:10:00.000Z",
    "payloadHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "currency": "USDT",
    "items": [{"serviceListingId":7,"base":{"raw":"100000000","currency":"USDT","decimals":6},"brandFee":{"raw":"5000000","currency":"USDT","decimals":6},"total":{"raw":"105000000","currency":"USDT","decimals":6}}],
    "totals": {"base":{"raw":"100000000","currency":"USDT","decimals":6},"brandFee":{"raw":"5000000","currency":"USDT","decimals":6},"total":{"raw":"105000000","currency":"USDT","decimals":6}}
  }
}

POST /api/v1/public/placement-orders/{id}/checkout
Idempotency-Key: <new stable UUID>
{ "quoteId": "9e955328-7a2b-42a4-9963-330fcc83ad92", "quoteVersion": 1, "payloadHash": "<copy the quote hash>", "confirm": true }

Quote 只向廣告主回傳基礎金額、品牌手續費與預留總額。用戶端顯示金額後，必須以 quoteId、quoteVersion、payloadHash 與 confirm:true 明確確認 checkout。廣告主 DTO 不包含創作者手續費與淨收入。創作者本人的定價回應包含基礎金額、創作者手續費與淨收入，不包含品牌手續費。

私人 UGC 自訂提案範例

POST /api/v1/public/placement-offers/quote
Idempotency-Key: <stable UUID>
{
  "origin": "CUSTOM",
  "creatorPublicId": "d8e805e4-1ec5-4ab6-a734-4ea389cecc6c",
  "serviceType": "UGC",
  "proofModes": ["PRIVATE_FILE"],
  "priceCents": "12000",
  "expectedEndAt": "2026-10-20T18:00:00.000Z",
  "quantity": 1,
  "discountBps": 0,
  "brief": "Create and deliver a short private product video.",
  "results": [{"expectedAt":"2026-10-20T17:00:00.000Z","description":"Deliver the private video"}],
  "rights": {"usage":"As agreed in the brief"}
}

# Quote response: { data: { quoteId, quoteVersion, payloadHash, items: [{ serviceListingId: null, base, brandFee, total }], totals, ... } }

POST /api/v1/public/placement-offers
Idempotency-Key: <new stable UUID>
{ "quoteId": "<quote ID>", "quoteVersion": 1, "payloadHash": "<quote hash>", "confirm": true }

# Without serviceListingId, only UGC + PRIVATE_FILE is accepted; do not send accountId or channelRef.

省略 serviceListingId 時，只接受 serviceType "UGC" 與 proofModes ["PRIVATE_FILE"]。請勿傳送 accountId 或 channelRef。Quote 只向廣告主顯示基礎金額、品牌手續費與預留總額，serviceListingId 為 null。FILE 結果的 channelRef 與 publishedRevision 為 null；url/contentId 也為 null，metrics 為空陣列。沒有公開網址或社群指標。

重試與錯誤

profile PATCH、page/generate、建立頻道、pricing PUT，以及契約明確要求的訂單、指派和 ownership 變更，都必須使用 UUID Idempotency-Key。結果未知時，以相同方法、路徑、UUID 與內容重試；相同金鑰搭配不同內容/操作/目標會回傳 IDEMPOTENCY_CONFLICT。Replay 前會重新檢查目前角色與所有權。Profile PATCH 回傳已保存的 DTO，page/generate 會重新建立預覽。Pricing PUT 回傳已保存的 operation/version 與最新 current projection；replay 不會再次執行金錢操作或價格變更。

結構化錯誤

錯誤回應包含穩定的 code 與安全訊息。可能代碼：API_KEY_INVALID（401）、API_KEY_MISSING_SCOPE / ROLE_NOT_ALLOWED / ACCOUNT_ACCESS_DENIED（403）、RESOURCE_NOT_FOUND（404）、INVALID_MONEY_PRECISION / INVALID_PROOF（400）、VERSION_CONFLICT / QUOTE_EXPIRED / PRICE_CHANGED / IDEMPOTENCY_CONFLICT / INSUFFICIENT_FUNDS（409）、RATE_LIMITED（429）、SERVICE_UNAVAILABLE / PRIVATE_UPLOAD_SERVICE_UNAVAILABLE（503）。他人的或無權存取的物件會顯示為找不到。

安全錯誤內容範例：

{"code":"IDEMPOTENCY_CONFLICT","message":"The idempotency key was used with a different payload."}