跳至主要內容
GetAPI
繁體中文
選單

GetAPI.ONE

使用 ONE 任務 API 生成影片

提交 OpenAI 形狀的影片任務,儲存公開任務 ID,透過 ONE 的準確狀態端點輪詢至終止狀態,並僅在完成後取得內容。

計費前確認協議

  • 選擇目前目錄中明確宣告 OpenAI 影片端點的模型。
  • 檢視即時價格與模型支援的輸入欄位;影片任務可能非同步執行併產生費用。
  • 首次接受計費的測試使用短小、低風險的提示詞。
text
POST https://www.getapi.one/v1/videos
GET https://www.getapi.one/v1/videos/{task_id}
GET https://www.getapi.one/v1/videos/{task_id}/content

提交、輪詢與取得

  1. 向 POST https://www.getapi.one/v1/videos 提交請求,並準確儲存返回的任務 ID。
  2. 以固定間隔和有上限的檢查次數輪詢 GET https://www.getapi.one/v1/videos/{task_id};等待期間不要新建任務。
  3. queued 或 in_progress 時繼續;僅 completed 視為成功停止。
  4. failed 時停止並展示錯誤。未知狀態應按非成功處理,並保留回應用於診斷。
  5. completed 後再取得 GET https://www.getapi.one/v1/videos/{task_id}/content。
  6. 在累計上限內以固定大小分塊寫入內容。範例使用 512 MiB 本地上限,並在讀取、驗證、寫入或取消失敗時刪除部分檔案。
提交任務
curl --fail-with-body https://www.getapi.one/v1/videos \
  -H "Authorization: Bearer $GETAPI_ONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<OPENAI_VIDEO_MODEL_ID_FROM_CURRENT_CATALOG>",
    "prompt": "A five-second locked-camera product turntable on a neutral background"
  }' > video-submit.json
最多輪詢 30 次,僅 completed 後取得
import json
import os
import time
from pathlib import Path
from urllib.parse import quote
from urllib.request import Request, urlopen

base_url = "https://www.getapi.one"
api_key = os.environ["GETAPI_ONE_API_KEY"]
submitted = json.loads(Path("video-submit.json").read_text(encoding="utf-8"))
task_id = submitted.get("id") or submitted.get("task_id")
if not task_id:
    raise ValueError("Submit response did not contain id or task_id")

safe_id = quote(task_id, safe="")
headers = {"Authorization": f"Bearer {api_key}"}
for attempt in range(30):
    request = Request(f"{base_url}/v1/videos/{safe_id}", headers=headers)
    with urlopen(request, timeout=30) as response:
        task = json.load(response)
    status = task.get("status")
    if status == "completed":
        break
    if status == "failed":
        raise RuntimeError(f"video task failed: {task.get('error')}")
    if status not in {"queued", "in_progress"}:
        raise RuntimeError(f"unknown non-success status: {status}")
    if attempt == 29:
        raise TimeoutError("video was not complete after 30 status checks")
    time.sleep(10)

content_request = Request(
    f"{base_url}/v1/videos/{safe_id}/content",
    headers=headers,
)
MAX_VIDEO_BYTES = 512 * 1024 * 1024
CHUNK_BYTES = 1024 * 1024
output_path = Path("result.mp4")
created_output = False
with urlopen(content_request, timeout=60) as response:
    content_type = response.headers.get_content_type()
    if not content_type.startswith("video/"):
        raise ValueError(f"unexpected content type: {content_type}")
    try:
        output = output_path.open("xb")
        created_output = True
        with output:
            total_bytes = 0
            while chunk := response.read(CHUNK_BYTES):
                total_bytes += len(chunk)
                if total_bytes > MAX_VIDEO_BYTES:
                    raise ValueError("video exceeds the local 512 MiB limit")
                output.write(chunk)
    except BaseException:
        if created_output:
            output_path.unlink(missing_ok=True)
        raise

實作狀態機

狀態用戶端動作
queued等待固定間隔後,在有上限的檢查次數內查詢同一任務 ID。
in_progress若有進度則展示,並繼續輪詢。
completed停止輪詢並請求內容端點。
failed停止輪詢,記錄安全的錯誤詳情,並要求使用者明確重試。

驗證預期結果

  • 提交回應提供任務 ID,用戶端以足夠持久的方式儲存它。
  • 每次狀態請求使用同一 ID,且不會建立重複任務。
  • 下載內容具有影片 Content-Type,並且僅在 completed 後開啟。

避免重複任務並恢復

  • 提交逾時時不要盲目重提:先檢查是否已生成任務 ID 或主控台記錄。
  • 輪詢遇到 404 時,核對公開任務 ID、準確的單複數路徑與同一帳戶金鑰。
  • failed 時,在修改輸入前保留模型、安全的請求摘要、任務 ID 與錯誤詳情。

保護媒體任務與結果

  • 將金鑰與任務查詢保留在已鑑權後端。
  • 轉發前按所選模型契約校驗提示詞、上傳檔案、時長、尺寸與數量。
  • 將獲批結果存入受控儲存;不要假設內容 URL 永久有效或適合公開。
  • 將累計下載上限設定在記憶體與儲存預算以內,以固定大小分塊寫入,並在下載未完成時清理部分產物。

下一步