所有文件 Nebula 文件所有端點互動式文件 Markdown OpenAPI JSON

REST API
預測

情緒預測

GET /forecasts/sentiment

GetSentimentForecast

該資產的情緒在接下來 72 小時內可能的走向，以各種結果及其機率構成的區間表示。series 會每 4 小時給出該步驟預期的看漲、看跌、中立及總貼文數，以及步驟結束時的 sentiment_signal，皆採用 /sentiment 尺度。chance_higher_24h 與 chance_higher_72h 給出訊號最終高於 current_sentiment_signal 的機率；其 _confident 標記會指出該機率明顯偏向某一方的時點。

預測會在有該資產新貼文的一分鐘內更新，且至少每 15 分鐘更新一次。refresh=true 會以最新資料重新計算，約需 5 秒；若超過 20 秒，你會取得最新預測並附帶 refreshed: false，收費 5。沒有預測的資產會傳回 status: not_forecastable 並附帶 reason；/forecasts/assets 會列出有預測的資產。

花費 5 點額度，加上 refresh=true 則為 10 點。not_forecastable 的回應免費，每個帳號每小時最多 30 次；超過之後，此端點會傳回 429，直到該小時結束。

此操作不支援錢包付款；請使用帳號驗證。x402 付款指南。

參數

asset_id string QUERY 必填

來自 /assets 或 /search 的資產 ID，例如 NVDA、GLD、SPX 或 bitcoin。請與一併回傳的 asset_class 一起送出。

Example:NVDA

asset_class string QUERY 必填

asset_id 所指資產的類別：equity（股票與 ETF）、commodity、index 或 crypto。請送出 /assets 或 /search 隨 asset_id 一併回傳的 asset_class。

允許的值

equitycommodityindexcrypto

Example:equity

refresh boolean QUERY

true 會以最新資料重新計算預測：10 點額度，約 5 秒。預設為 false。

Example:false

cURL 範例

curl --get \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/forecasts/sentiment' \
  --data-urlencode 'asset_id=NVDA' \
  --data-urlencode 'asset_class=equity' \
  --header 'X-API-Key: YOUR_API_KEY'

回應

200 OK

400 錯誤的要求

401 未經授權

402 額度已用完；回應會包含續約時間與已購買的額度餘額

403 禁止

404 找不到

405 不允許的方法；Allow 標頭會列出支援的方法

429 要求過多

500 內部伺服器錯誤

503 服務無法使用

媒體類型 application/json

as_of

string (date-time) 必填

預測的 UTC 起始時間：即用來計算的最後一個完整 15 分鐘區間的結束時間。當該資產從未被評分時為 null。

chance_higher_24h

number (double) 必填

情緒訊號在 24 小時後高於 current_sentiment_signal 的機率，介於 0 到 1。

chance_higher_24h_confident

boolean 必填

當 chance_higher_24h 低於 0.3 或高於 0.7 時為 true：預測明顯偏向某一方。越接近 0.5，就解讀為沒有明確方向。

chance_higher_72h

number (double) 必填

情緒訊號在 72 小時後高於 current_sentiment_signal 的機率，介於 0 到 1。

chance_higher_72h_confident

boolean 必填

當 chance_higher_72h 低於 0.3 或高於 0.7 時為 true：預測明顯偏向某一方。越接近 0.5，就解讀為沒有明確方向。

current_sentiment_signal

number (double) 必填

as_of 時的情緒訊號，採用 /sentiment 尺度：過去 24 小時內看漲貼文數減去看跌貼文數，較近期的貼文權重較高。所有路徑都由此開始，各項機率也以此為基準衡量。它可能與最新的 /sentiment 資料點略有差異，因為後者是每小時更新。

horizon_hours

integer 必填

預測涵蓋的時間長度，以小時為單位：固定為 72。

reason

string 必填

該資產無法預測的原因：too_little_history、stale_data 或 missing_price。當 status 為 ok 時為 null。

允許的值

too_little_historystale_datamissing_pricenull

refreshed

boolean 必填

當此請求重新執行預測時為 true（refresh=true 且重新執行及時完成）；若為最新的排程預測則為 false。

sample_paths

array<array<number (double)>> 必填

情緒訊號的 24 條可能路徑，每條都與 series 對齊。將它們繪製出來即可看出結果的分布範圍。

series

array<object> 必填

從 as_of 起每 4 小時的預測：共 18 個步驟，最舊的在前。

series[].bearish_posts

object 必填

僅此 4 小時步驟內預期的看跌貼文數，已排除機器人：類似 /sentiment 的區間貼文數，而非其過去 24 小時的累計數。

series[].bearish_posts.mean

number (double) 必填

此步驟預期的看跌貼文數。

series[].bearish_posts.p10

number (double) 必填

此步驟看跌貼文數的第 10 百分位數。

series[].bearish_posts.p25

number (double) 必填

此步驟看跌貼文數的第 25 百分位數。

series[].bearish_posts.p50

number (double) 必填

此步驟看跌貼文數的第 50 百分位數。

series[].bearish_posts.p75

number (double) 必填

此步驟看跌貼文數的第 75 百分位數。

series[].bearish_posts.p90

number (double) 必填

該步驟中看跌貼文的第 90 百分位數。

series[].bullish_posts

object 必填

僅此 4 小時步驟中預期的看漲貼文數，已排除機器人：如同 /sentiment 的區間貼文，而非其滾動 24 小時計數。

series[].bullish_posts.mean

number (double) 必填

該步驟中預期的看漲貼文數。

series[].bullish_posts.p10

number (double) 必填

該步驟中看漲貼文的第 10 百分位數。

series[].bullish_posts.p25

number (double) 必填

該步驟中看漲貼文的第 25 百分位數。

series[].bullish_posts.p50

number (double) 必填

該步驟中看漲貼文的第 50 百分位數。

series[].bullish_posts.p75

number (double) 必填

該步驟中看漲貼文的第 75 百分位數。

series[].bullish_posts.p90

number (double) 必填

該步驟中看漲貼文的第 90 百分位數。

series[].neutral_posts

object 必填

僅此 4 小時步驟中預期的中性貼文數，已排除機器人：如同 /sentiment 的區間貼文，而非其滾動 24 小時計數。

series[].neutral_posts.mean

number (double) 必填

該步驟中預期的中性貼文數。

series[].neutral_posts.p10

number (double) 必填

該步驟中中性貼文的第 10 百分位數。

series[].neutral_posts.p25

number (double) 必填

該步驟中中性貼文的第 25 百分位數。

series[].neutral_posts.p50

number (double) 必填

該步驟中中性貼文的第 50 百分位數。

series[].neutral_posts.p75

number (double) 必填

該步驟中中性貼文的第 75 百分位數。

series[].neutral_posts.p90

number (double) 必填

該步驟中中性貼文的第 90 百分位數。

series[].sentiment_signal

object 必填

該步驟結束時的 sentiment 訊號，採用 /sentiment 尺度：也就是該線最可能落在那裡。

series[].sentiment_signal.mean

number (double) 必填

該步驟結束時預期的 sentiment 訊號。

series[].sentiment_signal.p10

number (double) 必填

該步驟結束時 sentiment 訊號的第 10 百分位數。

series[].sentiment_signal.p50

number (double) 必填

該步驟結束時 sentiment 訊號的第 50 百分位數。

series[].sentiment_signal.p90

number (double) 必填

該步驟結束時 sentiment 訊號的第 90 百分位數。

series[].sentiment_signal.quantiles

array<number (double)> 必填

該步驟結束時 sentiment 訊號的 21 個分位數：第 0、5、10、……100 百分位數，由低至高排列。在它們之間內插，即可得出落在任一範圍的機率。

series[].timestamp

string (date-time) 必填

該步驟結束的 UTC 時間：as_of 加上 4、8、……72 小時。

series[].total_posts

object 必填

僅此 4 小時步驟中預期的貼文數（看漲、看跌與中性合計），已排除機器人：如同 /sentiment 的區間貼文，而非其滾動 24 小時計數。其百分位數是針對總數本身，因此並非三種類型百分位數的加總。

series[].total_posts.mean

number (double) 必填

該步驟中預期的貼文數（看漲、看跌與中性合計）。

series[].total_posts.p10

number (double) 必填

該步驟中貼文（看漲、看跌與中性合計）的第 10 百分位數。

series[].total_posts.p25

number (double) 必填

該步驟中貼文（看漲、看跌與中性合計）的第 25 百分位數。

series[].total_posts.p50

number (double) 必填

該步驟中貼文（看漲、看跌與中性合計）的第 50 百分位數。

series[].total_posts.p75

number (double) 必填

該步驟中貼文（看漲、看跌與中性合計）的第 75 百分位數。

series[].total_posts.p90

number (double) 必填

該步驟中貼文（看漲、看跌與中性合計）的第 90 百分位數。

status

string 必填

ok，或當該資產無法預測時為 not_forecastable（此時摘要欄位為 null，series 為空；原因請見 reason）。

允許的值

oknot_forecastable

turning

integer 必填

當 sentiment 轉為看漲時為 1（最近幾小時明顯比過去一天更偏看漲），轉為看跌時為 -1，其餘情況為 0。

允許的值

-101null

{
  "as_of": "2026-09-14T09:15:00Z",
  "chance_higher_24h": 0.74,
  "chance_higher_24h_confident": true,
  "chance_higher_72h": 0.61,
  "chance_higher_72h_confident": false,
  "current_sentiment_signal": 128.6,
  "horizon_hours": 72,
  "reason": null,
  "refreshed": false,
  "sample_paths": [
    [
      133.2,
      141.7
    ],
    [
      126.4,
      118.9
    ]
  ],
  "series": [
    {
      "bearish_posts": {
        "mean": 18,
        "p10": 9.9,
        "p25": 13.5,
        "p50": 17.1,
        "p75": 21.6,
        "p90": 27.9
      },
      "bullish_posts": {
        "mean": 46,
        "p10": 25.3,
        "p25": 34.5,
        "p50": 43.7,
        "p75": 55.2,
        "p90": 71.3
      },
      "neutral_posts": {
        "mean": 29,
        "p10": 16,
        "p25": 21.8,
        "p50": 27.6,
        "p75": 34.8,
        "p90": 45
      },
      "sentiment_signal": {
        "mean": 131.4,
        "p10": 92.9,
        "p50": 129.6,
        "p90": 175.5,
        "quantiles": [
          21.6,
          70.2,
          92.9,
          104.8,
          113.1,
          119.4,
          124.2,
          127.6,
          130.5,
          132.7,
          134.5,
          136.4,
          138.7,
          141.3,
          144.9,
          149.2,
          155.1,
          163.8,
          179.4,
          202.6,
          287.3
        ]
      },
      "timestamp": "2026-09-14T13:15:00Z",
      "total_posts": {
        "mean": 93,
        "p10": 51.2,
        "p25": 69.8,
        "p50": 88.4,
        "p75": 111.6,
        "p90": 144.2
      }
    },
    {
      "bearish_posts": {
        "mean": 19,
        "p10": 10.5,
        "p25": 14.3,
        "p50": 18.1,
        "p75": 22.8,
        "p90": 29.5
      },
      "bullish_posts": {
        "mean": 50,
        "p10": 27.5,
        "p25": 37.5,
        "p50": 47.5,
        "p75": 60,
        "p90": 77.5
      },
      "neutral_posts": {
        "mean": 31,
        "p10": 17.1,
        "p25": 23.3,
        "p50": 29.5,
        "p75": 37.2,
        "p90": 48.1
      },
      "sentiment_signal": {
        "mean": 137.6,
        "p10": 99.1,
        "p50": 135.79999999999998,
        "p90": 181.7,
        "quantiles": [
          21.6,
          70.2,
          92.9,
          104.8,
          113.1,
          119.4,
          124.2,
          127.6,
          130.5,
          132.7,
          134.5,
          136.4,
          138.7,
          141.3,
          144.9,
          149.2,
          155.1,
          163.8,
          179.4,
          202.6,
          287.3
        ]
      },
      "timestamp": "2026-09-14T17:15:00Z",
      "total_posts": {
        "mean": 100,
        "p10": 55,
        "p25": 75,
        "p50": 95,
        "p75": 120,
        "p90": 155
      }
    }
  ],
  "status": "ok",
  "turning": 0
}