Ir al contenido
GetAPI
Español
Menú

GetAPI.ONE

Generar vídeo con la API de tareas ONE

Envíe una tarea de vídeo con formato OpenAI, conserve su ID público, consulte la ruta exacta de estado ONE hasta un estado final y recupere el contenido solo después de completarse.

Confirmar el protocolo antes de gastar

  • Elija un modelo actual del catálogo que declare explícitamente el endpoint de vídeo OpenAI.
  • Revise los precios en vivo y los campos de entrada admitidos; el trabajo de vídeo puede ser asíncrono y facturable.
  • Use una instrucción breve y de bajo riesgo en la primera prueba aceptada.
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

Enviar, consultar y recuperar

  1. Envíe POST https://www.getapi.one/v1/videos y guarde exactamente el ID de tarea devuelto.
  2. Consulte GET https://www.getapi.one/v1/videos/{task_id} a intervalos fijos y con un número limitado de comprobaciones; no cree otra tarea mientras espera.
  3. Continúe con queued o in_progress; finalice con éxito únicamente con completed.
  4. Deténgase y muestre el error ante failed. Trate estados desconocidos como resultados sin éxito y conserve la respuesta para diagnóstico.
  5. Después de completed, obtenga GET https://www.getapi.one/v1/videos/{task_id}/content.
  6. Transfiera el contenido en bloques de tamaño fijo con un límite acumulado. El ejemplo usa un máximo local de 512 MiB y elimina el archivo parcial ante cualquier fallo de lectura, validación, escritura o cancelación.
Enviar la tarea
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
Consultar como máximo 30 veces y recuperar solo después de 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

Implementar la máquina de estados

EstadoAcción del cliente
queuedEsperar el intervalo fijo y consultar el mismo ID dentro del número limitado de comprobaciones.
in_progressMostrar el progreso si se proporciona y seguir consultando.
completedDejar de consultar estado y solicitar la ruta de contenido.
failedDejar de consultar, registrar los detalles seguros del error y exigir un reintento deliberado.

Verificar el resultado esperado

  • La respuesta de envío proporciona un ID de tarea que el cliente almacena con persistencia suficiente para el flujo.
  • Cada consulta de estado usa el mismo ID y nunca crea trabajo duplicado.
  • El contenido descargado tiene un tipo de contenido de vídeo y se abre solo después de completed.

Recuperarse sin duplicar tareas

  • Si se agota el tiempo de envío, no lo repita a ciegas: compruebe si se creó un ID de tarea o registro de consola.
  • Ante 404 al consultar estado, verifique el ID público, la ruta exacta singular o plural y la misma clave de cuenta.
  • Ante failed, conserve modelo, resumen seguro de la solicitud, ID de tarea y detalles del error antes de modificar entradas.

Proteger tareas y resultados multimedia

  • Mantenga la clave y las consultas de tareas en su backend autenticado.
  • Valide instrucciones, archivos, duración, dimensiones y cantidades frente al contrato del modelo elegido antes de reenviar.
  • Guarde resultados aprobados en almacenamiento controlado; no suponga que una URL de contenido es permanente o segura para publicación.
  • Defina un límite acumulado de descarga inferior a su presupuesto de memoria y almacenamiento, transfiera bloques de tamaño fijo y limpie archivos parciales si la descarga no termina.

Próximos pasos