建立動畫匯出

從原始碼生成 POST /animation-exports 的鑑權、欄位、響應、錯誤與安全呼叫參考。

公開測試API v1 · 1.4.0最後核實 2026-09-15

本頁目錄

操作

POST /animation-exports

operationId: create_animation_export_v1_animation_exports_post

啟動付費非同步任務。先報價並取得使用者批准，立即儲存任務 ID；202 僅代表已接受。響應不明時複用同一冪等鍵、憑據身份與未修改的請求。建立時重新計價；API 報價不鎖價，max_credits/quote_id 不是 API 請求欄位。遵循 Retry-After 輪詢，所有終態（包括失敗）都需檢查 outputs。

鑑權與副作用

使用可信環境中的 Bearer API Key。所需權限：animations:write

此操作建立付費任務，提交前取得批准。API 報價不鎖價，也不強制執行最高預算。

引數

引數	位置	型別	必填	約束 / 預設值	含義
`Idempotency-Key`	`header`	`string`	是	`minLength`: `8`; `maxLength`: `200`	每次邏輯操作生成並儲存一次；同一憑據和未修改請求重試時複用，更換憑據會改變去重範圍。

請求體 (application/json)

請求體必填：true

欄位	型別	必填	預設值	約束	含義
`export`	ExportOptions	否	`{"fps":null,"frame_count":24,"output_formats":["spritesheet"],"output_height":512,"output_width":512,"transparent":{"enabled":false},"unity":{"pivot":"bottom_center","pixels_per_unit":100}}`	—	輸出格式及處理設定。
`metadata`	`object`	否	`{}`	—	簡單標量或 null 後設資料，JSON 不超過 4 KiB，不包含憑據。
`selection`	Selection	否	`{"duration_seconds":null,"mode":"full","start_seconds":0}`	—	需要匯出的源影片區間。
`source_video_asset_id`	`string`	是	—	`format`: `uuid`	所屬源影片資產 ID，不是任務 ID；複用已有影片可避免重新生成動作。

完整巢狀結構：AnimationExportCreateRequest

請求示例

json

{
  "export": {
    "fps": 12,
    "output_formats": [
      "spritesheet",
      "spritesheet_json"
    ],
    "output_height": 512,
    "output_width": 512
  },
  "selection": {
    "duration_seconds": 2,
    "mode": "range",
    "start_seconds": 1
  },
  "source_video_asset_id": "00000000-0000-4000-8000-000000000003"
}

請求示例

json

{
  "export": {
    "frame_count": 24,
    "output_formats": [
      "frames_zip"
    ],
    "output_height": 512,
    "output_width": 512
  },
  "selection": {
    "mode": "full"
  },
  "source_video_asset_id": "00000000-0000-4000-8000-000000000003"
}

響應

HTTP	正文	含義
`202`	TaskResponse	已接受非同步任務，請儲存任務 ID 並輪詢。
`400`	APIErrorEnvelope	輸入錯誤，修正請求後再嘗試。
`401`	APIErrorEnvelope	API Key 缺失、到期或被撤銷。
`402`	APIErrorEnvelope	點數不足，不自動購買。
`403`	APIErrorEnvelope	帳戶資格、帳戶狀態或 Key 權限不允許此操作。
`404`	APIErrorEnvelope	資源不可用、不屬於當前使用者，或簽名無效/過期。
`409`	APIErrorEnvelope	冪等衝突；僅 IDEMPOTENCY_IN_PROGRESS 可複用原請求重試。
`413`	APIErrorEnvelope	請求或解碼後的圖片超過配置限制。
`415`	APIErrorEnvelope	使用支援的圖片媒體型別。
`422`	APIErrorEnvelope	圖片解碼後尺寸超過限制。
`429`	APIErrorEnvelope	觸發帳戶級速率或佇列限制，遵循 Retry-After 等待。
`500`	APIErrorEnvelope	內部錯誤，保留任務 ID 和冪等鍵，僅標記可重試時重試。
`503`	APIErrorEnvelope	服務或供應商不可用，僅 error.retryable 為 true 時重試。

響應頭

HTTP	響應頭	型別	含義
`202`	`Retry-After`	`integer`	建議等待秒數，遵循服務值並設定總體截止時間。
`429`	`Retry-After`	`integer`	建議等待秒數，遵循服務值並設定總體截止時間。
`503`	`Retry-After`	`integer`	建議等待秒數，遵循服務值並設定總體截止時間。

響應示例

json

{
  "created_at": "2026-08-30T00:00:00Z",
  "credits": {
    "charged": 0,
    "held": 1,
    "quoted": 1
  },
  "error": null,
  "finished_at": null,
  "id": "00000000-0000-4000-8000-000000000002",
  "metadata": {},
  "normalized_input": {},
  "object": "animation_export",
  "outputs": [],
  "progress": 0,
  "stage": "queued",
  "started_at": null,
  "status": "queued"
}

這篇文件有幫助嗎？

允許文件互動分析

不收集搜尋字詞、程式碼或自由文字。此開關僅控制文件互動事件。隱私權政策

需要協助？聯絡支援

搜尋文件

建立動畫匯出

操作

鑑權與副作用

引數

請求體 (application/json)

請求示例

請求示例

響應

響應頭

響應示例

相關教程

這篇文件有幫助嗎？