本文へ移動
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 を使い、重複した処理を作成しないこと。
  • ダウンロード内容のコンテンツタイプが動画であり、completed の後にのみ開くこと。

タスクを重複させずに復旧

  • 送信がタイムアウトしても無条件に再送せず、タスク ID やコンソール記録が作成されたか確認します。
  • 状態照会で 404 が出た場合は、公開タスク ID、ルートの正確な単数形と複数形、同じアカウントキーを確認します。
  • failed の場合は、入力を変える前にモデル、安全なリクエスト概要、タスク ID、エラー詳細を保存します。

メディアタスクと結果を保護

  • キーとタスクの照会は認証済みバックエンドに保持します。
  • 転送前に、プロンプト、アップロード、時間、寸法、個数を選択モデルの仕様に照らして検証します。
  • 承認済みの結果を管理下のストレージに保存します。コンテンツ URL が永続的、または公開して安全とは想定しないでください。
  • メモリーとストレージの予算を下回る累積ダウンロード上限を設定し、固定サイズのチャンクで処理します。完了しなかったダウンロードの部分ファイルは削除してください。

次の手順