Kode error API video AI: artinya dan kapan harus mencoba ulang

Dua tempat error bisa muncul

Job video atau gambar bisa gagal di dua momen, dan kode Anda harus menangani keduanya:

1. Saat Anda mengirim. POST /v1/generations menjawab dengan status error HTTP dan body seperti {"error": {"code": "...", "message": "..."}}. Tidak ada yang dimulai dan tidak ada yang ditagih.
2. Saat job berjalan. Submit berhasil dengan 202, tetapi job kemudian berakhir dengan status: "failed". error-nya berisi code, message yang bisa Anda tampilkan kepada orang yang meminta, dan retryable.

Job yang gagal tidak pernah ditagih di model mana pun. Harganya ditahan dari saldo Anda saat submit dan dilepas kembali jika job gagal.

Error HTTP saat submit

Aturan praktisnya: 429, 500 dan 503 layak dicoba ulang dengan backoff; semua kode di rentang 4xx kecuali 429 berarti permintaannya sendiri harus diubah.

Mengapa job gagal setelah dimulai

Di balik layar, job yang menemui rute sibuk atau rusak akan pindah sendiri ke rute berikutnya, jadi saat Anda melihat model_busy atau all_routes_failed, semua rute sudah dicoba. Field attempts menyebutkan jumlahnya. Menunggu satu atau dua menit sebelum mencoba lagi biasanya sudah cukup.

Penolakan konten

content_policy adalah kegagalan yang paling sering dialami. Modellah, bukan API, yang memutuskannya, dan reason memberi tahu aturan mana yang aktif. Penyebab umumnya adalah nama atau wajah orang terkenal di prompt atau gambar referensi (real_person), merek dan karakter terkenal (copyright), serta apa pun yang terbaca melibatkan anak di bawah umur. Mencoba ulang permintaan yang sama tidak akan membantu; ubah kata-kata prompt atau ganti gambarnya. Tingkat ketatnya berbeda antarmodel, jadi prompt yang sama bisa lolos di satu model dan ditolak di model lain.

Loop retry yang melakukan hal yang benar

Helper Python ini mencoba ulang apa yang layak dan berhenti pada apa yang tidak. Dua detail penting:

• Mengirim ulang submit setelah 503 atau koneksi terputus memakai sama Idempotency-Key yang sama, sehingga tidak akan pernah memulai job kedua yang berbayar.
• Mencoba lagi setelah job gagal memakai kunci baru. Kunci yang sama hanya akan mengembalikan job yang gagal itu.

import os
import time
import uuid

import requests

API = "https://api.revana.si/v1"
AUTH = {"Authorization": f"Bearer {os.environ['REVANA_API_KEY']}"}
RETRY_HTTP = {429, 500, 503}


class GenerationError(Exception):
    pass


def submit(body):
    """POST a job. Retries 429, 500 and 503 with the same Idempotency-Key, so a retry never starts a second job."""
    headers = {**AUTH, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(6):
        r = requests.post(f"{API}/generations", headers=headers, json=body, timeout=60)
        if r.ok:
            return r.json()
        if r.status_code in RETRY_HTTP:
            time.sleep(float(r.headers.get("Retry-After", 2 ** attempt)))
            continue
        err = r.json()["error"]  # 400, 401, 402, 403, 409, 413, 422: fix the request, do not retry
        raise GenerationError(f"{r.status_code} {err['code']}: {err['message']}")
    raise GenerationError("still busy after 6 tries")


def wait(job):
    while job["status"] in ("queued", "running"):
        time.sleep(5)
        job = requests.get(f"{API}/generations/{job['id']}", headers=AUTH).json()
    return job


def generate(body, tries=3):
    for n in range(tries):
        job = wait(submit(body))  # each call uses a new key: a failed job is final
        if job["status"] == "succeeded":
            return job
        err = job["error"]
        if not err["retryable"]:
            raise GenerationError(f"{err['code']}: {err['message']}")
        time.sleep(60 * (n + 1))  # model_busy, timeout and the like: wait, then try again
    raise GenerationError(f"gave up after {tries} tries: {err['code']}")


job = generate({
    "model": "seedance-2.0-fast",
    "input": {"prompt": "Waves roll onto black sand at sunset.", "resolution": "480p", "duration": 5},
    "max_cost_usd": 0.3,
})
print(job["output"]["urls"][0], job["cost_usd"])

Job contoh adalah klip Seedance 2.0 Fast 480p berdurasi 5 detik, yang berharga $0.25 jika berhasil dan gratis jika gagal. Batas max_cost_usd mencegah pengaturan yang salah menghabiskan biaya lebih dari perkiraan.

Menghindari error sejak awal

• Baca opsinya sebelum mengirim. GET /v1/models dan halaman model mencantumkan ukuran, durasi, dan batas referensi setiap model. Nilai di luar daftar itu langsung ditolak dengan 422 invalid_input.
• Unggah file, jangan disematkan. POST /v1/uploads menerima gambar hingga 30 MB, klip hingga 50 MB, dan suara hingga 15 MB, lalu mengembalikan tautan yang berlaku 14 hari, sehingga body permintaan tetap kecil.
• Periksa saldo Anda lewat kode. GET /v1/balance sebelum batch besar menghindarkan Anda dari rentetan error 402. Paket kredit ada di halaman harga.

Untuk cara memangkas biaya job yang berhasil, lihat cara memangkas biaya API video AI. Referensi error lengkap ada di dokumentasi; dapatkan kunci API untuk mencobanya.