WORKSPACE

接入指南

API Keys
DEVELOPER DOCUMENTATION

用圖片與影片，實現你的創意。

一組 API Key，統一的任務式生成流程。

目前只開放 NSFW 圖片與影片模型。提交前會依頁面顯示的 Nightfolio 售價預留額度，成功後扣費。

快速開始

註冊並驗證信箱、登入後建立 API Key、增加額度，再選擇已開放的 NSFW 圖片或影片模型。帳戶可用額度必須足以支付本次報價。

Base URL https://developer.nightfolioai.com/v1

兼容範圍：GET /v1/models 採用 OpenAI 清單格式。圖片與影片使用 Nightfolio AI 非同步任務（202 加輪詢），不能直接替換 OpenAI SDK 回傳格式。尚不支援 Claude Messages（/v1/messages）、Responses、圖片編輯與參考素材；Chat Completions 接口已實作，但目前未上架文字模型。

curl
curl "https://developer.nightfolioai.com/v1/images/generations" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
  "model": "NSFW-Seedream-4.5",
  "prompt": "A small ceramic vase on a warm gray background."
}'

身份驗證

請在 Authorization 標頭帶上你的 Nightfolio AI API Key，不需要供應商 Key。Key 應放在你自己的應用伺服器；撤銷後立即失效。

HTTP
Authorization: Bearer mh_YOUR_API_KEY

每次新的生成需要 Idempotency-Key（1–100 字元），請在送出前儲存。重試同一操作時，必須使用原本的 Key 與內容。

模型與定價

GET /v1/models 只返回已開放的 NSFW 圖片與影片模型。目錄單位售價與固定規格的每次生成報價均採用相同的 Nightfolio 定價；提交前會預留並將報價保存在任務中。

cURL
curl "https://developer.nightfolioai.com/v1/models" -H "Authorization: Bearer $NIGHTFOLIO_API_KEY"

查看模型與固定參數 →

圖片生成

POST /v1/images/generations

文字生圖，每次一張。接口立即返回 HTTP 202 與 Nightfolio AI 任務 ID，透過 GET /v1/images/{id} 取得結果。這是 Nightfolio AI 的非同步接口，並非 OpenAI 同步圖片回傳格式。

cURL
curl "https://developer.nightfolioai.com/v1/images/generations" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
  "model": "NSFW-Seedream-4.5",
  "prompt": "A small ceramic vase on a warm gray background."
}'

必填 model 與 prompt（1–8,000 字元）。若傳入規格參數，必須與目錄完全一致。本版暫不支援任意尺寸、多張圖片、圖片編輯、回呼、extra_body 或參考素材。

影片生成

POST /v1/videos/generations

文字生影片。返回 HTTP 202 後，查詢 GET /v1/videos/{id}。時長、解析度、比例與音訊設定以模型規格為準，不需要傳入 async。

cURL
curl "https://developer.nightfolioai.com/v1/videos/generations" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_UNIQUE_REQUEST_ID" \
  -d '{
  "model": "NSFW-Seedance-2.0-fast",
  "prompt": "A slow camera movement through a sunlit forest."
}'

Seedance 2.x 可透過 input_references: [{"type":"image","url":"asset://<asset-id>","role":"reference_image"}] 使用素材庫中的一張有效圖片。此版暫不提供音訊／影片輸入、首尾幀控制或影片編輯。

任務與結果

JSON · accepted
{
  "id": "mh_image_JOB_ID",
  "object": "image",
  "model": "NSFW-Seedream-4.5",
  "status": "queued",
  "created_at": 1788696000,
  "charge": 0,
  "reserved": 50000,
  "billing_status": "processing",
  "result_expires_at": 0
}

上方金額僅供格式示意，不是報價。回應金額單位為 micro-USD：1 美元 = 1,000,000 單位。

cURL
curl "https://developer.nightfolioai.com/v1/images/mh_image_JOB_ID" \
  -H "Authorization: Bearer $NIGHTFOLIO_API_KEY"
Status說明
queued等待提交
submitting正在提交生成
processing正在生成，請繼續查詢
completed結果已完成，費用已結算
failed生成失敗，預留額度已釋放
needs_review結果未明，額度保留待人工核對

完成後，圖片位於 result.data[0].b64_json 或 url；影片位於 result.data[0].url。請及時儲存：結果資料保留 24 小時，外部下載連結可能更早到期。只有任務所屬帳戶可查詢。

計費與重試

提交前會預留額度，成功後依任務保存的報價扣費一次；報價依所選模型與請求參數計算。確認失敗會釋放額度；提交中斷或結果不明會保留額度待核對。不要因逾時而直接重新生成。

重試提交時沿用相同 Idempotency-Key 與內容；已取得 ID 就查詢原任務。建議每 5–10 秒查詢一次，遇到 429 延長間隔。每帳戶每分鐘最多提交 12 次、查詢 120 次，同時最多 4 個進行中請求。

錯誤處理

JSON
{
  "error": {
    "code": "model_not_published",
    "message": "This model is not published."
  }
}
HTTP處理方式
400檢查必填欄位與固定規格
401檢查 Key 或帳戶狀態
402請管理員增加額度
404檢查模型、任務 ID 與所屬帳戶
409Idempotency-Key 與之前的內容衝突
429降低頻率，不要重複建立任務
503模型未開放或服務尚未配置