按能力

圖片

選模型、複製請求、拿到圖片。下面的內容都跟著你選的模型變。

#1. 選模型

doubao-seedream-5-0-pro$0.02928 / 次非同步任務限制和狀態

這個能力有 12 個線上模型,切換後下面的程式碼會跟著變。

#2. 複製請求

把 YOUR_API_KEY 換成你的金鑰再執行。顯示的選項都是這個模型支援的。

POSThttps://www.aisplice.store/v1/images/tasksBearer API key非同步任務

選項這裡只顯示目前模型已公開支援的選項。

# Requires curl and jq
API_KEY="${API_KEY:-YOUR_API_KEY}"

# 1. Submit once
SUBMITTED=$(curl --fail-with-body -sS https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: model-docs-$(date +%s)-$$" \\
  -d '{
  "model": "Seedream 5.0 Pro",
  "prompt": "A cinematic scene with careful composition",
  "size": "auto",
  "resolution": "1K",
  "n": 1,
  "output_format": "jpeg",
  "watermark": false,
  "optimize_prompt_options": {
    "mode": "standard"
  }
}')
TASK_ID=$(printf '%s' "$SUBMITTED" | jq -r '.task_id // .id // empty')
if [ -z "$TASK_ID" ]; then
  printf '%s\n' "$SUBMITTED" >&2
  exit 1
fi
echo "task_id=$TASK_ID"

# 2. Poll until terminal
while true; do
  STATUS_JSON=$(curl --fail-with-body -sS \
    "https://www.aisplice.store/v1/images/tasks/$TASK_ID" \
    -H "Authorization: Bearer $API_KEY")
  STATUS=$(printf '%s' "$STATUS_JSON" | jq -r '.status // empty' | tr '[:upper:]' '[:lower:]')
  echo "status=$STATUS"
  case "$STATUS" in
    completed|succeeded|success) break ;;
    failed|failure|cancelled|canceled)
      printf '%s\n' "$STATUS_JSON" | jq .
      exit 1
      ;;
  esac
  sleep 3
done

# 3. Fetch the final result
curl --fail-with-body -sS \
  "https://www.aisplice.store/v1/images/tasks/$TASK_ID/content" \
  -H "Authorization: Bearer $API_KEY" | jq .

正式環境建議使用公開媒體網址。 先上傳本機檔案,再把 public_url 放入模型請求;避免傳送大體積 Base64 請求主體。

檢視上傳指南

全部參數

這個模型支援的全部欄位和可選值。

model
string必填

本次請求使用的精確模型識別碼。

doubao-seedream-5-0-pro
prompt
string選填

Generation/editing instruction. Optional only when layer_decomposition is true. Point and box tags use normalized 0..1000 coordinates.

images
string[]選填

Optional reference image URLs or data URIs, up to 10. Layer decomposition and transparent editing require exactly one image.

size
string選填

auto, 1K, 1.5K, 2K, a supported aspect ratio, or an exact WIDTHxHEIGHT value. Exact pixels must total 921600..4624220.

resolution
string選填

請求的輸出解析度。

1K1.5K2K
n
integer選填
1

回應流程

檢視任務狀態、終態和結果回應範例。

提交
{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "image.task",
  "model": "Seedream 5.0 Pro",
  "status": "queued"
}
結果內容
{
  "created": 1720000000,
  "data": [
    {
      "url": "https://media.example/result.png"
    }
  ]
}

等待中

queued · submitted · in_progress · processing

成功

completed · succeeded · success

失敗

failed · failure · cancelled · canceled

全部欄位:見 API 參考裡的 /v1/images/tasks →

#3. 拿到結果

提交後馬上回傳 task_id。每隔幾秒查一次,直到 status 變成 completed;也可以傳 webhook_url,完成後我們會回呼你。

GET https://www.aisplice.store/v1/images/tasks/{task_id}

GET https://www.aisplice.store/v1/images/tasks/{task_id}/content

成功才扣費

失敗或取消的任務自動退款,請求日誌裡能看到每個任務的最終費用。

狀態值和輪詢方式 →改用回呼,不用反覆查詢 →

#出錯了怎麼辦

  • 400 並提示某個欄位:這個模型不支援該選項,用第 2 步列出的取值。
  • 內容被模型拒絕:換個說法重寫提示詞;被拒絕的請求不扣費。
  • 402:餘額不夠這次請求,到「錢包」儲值後重試。
  • 429:請求太快,按 Retry-After 給的秒數等一下再試。
  • 503 model_not_found:模型名寫錯了或模型暫時下線,從第 1 步重新選一個。

查詢其他錯誤 →

#參考圖

在第 2 步列出的參考圖欄位裡填公開的圖片網址。本機檔案先上傳,再用回傳的網址。

怎麼上傳本機檔案 →

做進你的產品裡先給你的使用者放哪些選項,哪些以後再加。
先給使用者放哪些選項先放提示詞和一個影響價格的選項,基礎流程跑通後再加其他的。+

創作意圖

像 prompt 這樣的欄位應該出現在 UI 中,因為使用者能直接理解它會改變什麼結果。

成本倍率項

像 duration、resolution、size、count 這樣的欄位,只有在價格已經能被清楚解釋時才應引入。

模式切換項

像 image、mask 或 continuation ID 這類欄位會改變整個工作流程本身,只應出現在專門模式中。

系統接線項

像 webhook_secret 這樣的欄位是給整合方用的,不是給一般創作者用的,所以不要放進預設 UI。

  • prompt
    何時開放
    始終開放。它是圖片任務最核心的創作輸入。
    建議預設值
    在 UI 中設為必填。
    為什麼重要
    它直接決定產出結果;隱藏後功能基本不可用。
  • size
    何時開放
    如果計費會隨輸出尺寸變化,第一版就應開放。
    建議預設值
    先只提供一個建議長寬比,例如 1:1。
    為什麼重要
    它同時影響成本和畫面構圖,所以使用者通常需要一個簡單的尺寸選擇。
  • quality
    何時開放
    只有當使用者明確要求更高或更便宜的檔位時再開放。
    建議預設值
    在伺服器端保持模型預設值。
    為什麼重要
    它會改變價格和延遲,但通常不需要成為第一天就開放的控制項。
  • n
    何時開放
    只有當批次生成是核心工作流程時才開放。
    建議預設值
    預設為 1。
    為什麼重要
    它會立刻放大成本,也容易讓首版體驗變得複雜嘈雜。
  • mask / image
    何時開放
    僅在編輯類或參考圖類產品中開放。
    建議預設值
    在文生圖模式中隱藏。
    為什麼重要
    這些欄位會把產品從「生成」切換成「編輯」,因此不應混入基礎流程。
recommended-rollout.txt
Phase 1
- prompt
- one size or one duration default
- submit -> poll -> content

Phase 2
- one quality or resolution selector
- clear pricing hint

Phase 3
- advanced controls such as reference media, continuation, webhook, or vendor-specific tuning

結果只保留一個可信來源

任務完成後,讓應用程式統一圍繞 /content 回傳的平台 URL 運作。這樣既能隱藏上游供應商細節,也能讓歷史回放更穩定。

還是沒解決?

把請求 ID 或錯誤訊息傳給我們,我們來查。