본문으로 건너뛰기
GetAPI
대시보드
한국어
화면 모드
알림
알림
불러오는 중…
메뉴

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

다음 단계