본문으로 건너뛰기
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이 영구적이거나 공개해도 안전하다고 가정하지 마세요.
  • 메모리와 저장소 예산보다 낮은 누적 다운로드 한도를 설정하고 고정 크기 청크로 스트리밍하며 다운로드가 끝나지 않으면 부분 파일을 정리하세요.

다음 단계