URL dasar OpenAI-compatible yang stabil untuk tim produk Seedance API

Pemindahan produk text-to-video dari satu setup penyedia ke setup lain seharusnya tidak mengharuskan penulisan ulang semua helper autentikasi, variabel lingkungan, aturan retry, dan hook observabilitas. Pola yang lebih aman adalah memisahkan bagian integrasi Anda yang dapat tetap stabil dari bagian yang khusus untuk pembuatan video.

Untuk tim yang sudah menggunakan klien bergaya OpenAI, Flatkey menyediakan titik awal yang praktis: buat satu API key, setel base URL klien ke https://router.flatkey.ai/v1, jalankan request kecil yang kompatibel, dan konfirmasi request tersebut di Usage Logs. Itu membuktikan lapisan koneksi bersama sebelum Anda menambahkan workflow video asinkron khusus Seedance.

Panduan ini menunjukkan cara membuat migrasi tersebut terkontrol, dapat dibalik, dan mudah diperiksa.

Jawaban singkat

Base URL OpenAI-compatible yang stabil dapat mengurangi pekerjaan migrasi untuk bagian bersama dari integrasi AI:

• injeksi API key
• konfigurasi lingkungan
• inisialisasi klien
• korelasi request
• kebijakan retry dan timeout
• pemantauan penggunaan dan biaya

Ini tidak berarti setiap penyedia text-to-video menggunakan body request yang sama atau endpoint yang sama. Pembuatan video umumnya memerlukan alur asinkron terpisah: buat job, simpan job ID, lakukan polling atau terima webhook, lalu ambil aset final.

Karena itu, tujuan implementasinya bukan “memaksa Seedance melalui bentuk chat-completions.” Tujuannya adalah “menjaga koneksi gateway tetap stabil, lalu mengisolasi adapter job khusus video di balik antarmuka kecil.”

Mengapa stabilitas base URL penting untuk produk text-to-video

Migrasi penyedia biasanya gagal pada titik sambungan di sekitar pemanggilan model, bukan pada satu baris yang menyebutkan model. Aplikasi produksi dapat memiliki API key di secrets manager, klien HTTP di beberapa layanan, worker antrean, handler webhook, log audit, peringatan pengeluaran, dan setelan rollback.

Jika setiap penyedia dihubungkan langsung ke semua lapisan itu, menambahkan model video baru menjadi perubahan infrastruktur yang luas. Batas gateway yang stabil membatasi blast radius.

Hasilnya adalah permukaan migrasi yang lebih kecil. Kode produk Anda tetap bergantung pada antarmuka internal yang stabil, sementara adapter menangani perbedaan dalam API video.

Urutan migrasi yang paling aman

Gunakan dua pemeriksaan terpisah alih-alih mencoba memvalidasi seluruh jalur video dalam satu request.

1. Smoke test koneksi: verifikasi autentikasi, base URL yang kompatibel dengan OpenAI, akses jaringan, dan Usage Logs.
2. Uji alur kerja video: verifikasi route Seedance saat ini, parameter yang diterima, transisi status asinkron, pengiriman aset, dan perilaku penagihan.

Pemisahan ini membuat kegagalan lebih mudah diklasifikasikan. Jika smoke test gagal, masalahnya kemungkinan ada pada kredensial, konfigurasi base URL, jaringan, atau penanganan request bersama. Jika smoke test lolos tetapi pekerjaan video gagal, fokuslah pada route model dan adapter video.

Step 1: pindahkan base URL ke konfigurasi

Jangan hardcode URL provider di logika aplikasi. Letakkan koneksi gateway di environment variables agar deployment dan rollback tidak memerlukan perubahan kode.

FLATKEY_API_KEY=sk-fk-replace-me
AI_BASE_URL=https://router.flatkey.ai/v1
AI_SMOKE_TEST_MODEL=gpt-4o-mini
VIDEO_PROVIDER=flatkey
VIDEO_MODEL=replace-with-current-seedance-route

Perlakukan nilai model video sebagai setting saat deployment. Alias model dan kemampuan yang didukung dapat berubah, jadi pastikan route terkini di Flatkey sebelum rollout, alih-alih menyalin identifier lama dari posting blog.

Step 2: inisialisasi client OpenAI-style yang sudah ada sekali saja

Jika aplikasi Anda sudah menggunakan OpenAI Python SDK, perubahan koneksi bersama ini memang sengaja dibuat kecil.

import os
from openai import OpenAI


client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.getenv("AI_BASE_URL", "https://router.flatkey.ai/v1"),
)

Konfigurasi TypeScript yang setara mempertahankan batas yang sama:

import OpenAI from "openai";

export const aiClient = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.AI_BASE_URL ?? "https://router.flatkey.ai/v1",
});

Keputusan desain yang penting adalah bahwa layanan mengimpor client yang sudah dikonfigurasi, alih-alih membangun client khusus provider mereka sendiri di seluruh codebase.

Step 3: jalankan smoke test koneksi sebelum menyentuh job video

Quickstart Flatkey menggunakan request chat-completions yang kompatibel dengan OpenAI lalu meminta Anda memverifikasi panggilan tersebut di Usage Logs. Gunakan test kecil itu untuk membuktikan lapisan integrasi bersama.

import os

from app.ai_client import client


def verify_gateway_connection() -> dict:
    response = client.chat.completions.create(
        model=os.getenv("AI_SMOKE_TEST_MODEL", "gpt-4o-mini"),
        messages=[
            {"role": "user", "content": "Reply with: gateway connection verified"}
        ],
        max_tokens=20,
    )

    return {
        "request_model": response.model,
        "finish_reason": response.choices[0].finish_reason,
        "usage": response.usage.model_dump() if response.usage else None,
    }

Request ini bukan menguji pembuatan video Seedance. Ini memverifikasi empat prasyarat yang dibutuhkan kedua alur kerja:

• kunci ada dan diterima
• base URL benar
• aplikasi dapat menjangkau router
• request muncul di dashboard dengan data usage

Untuk penelusuran langkah pertama secara detail, gunakan quickstart Seedance API untuk tim produk.

Langkah 4: letakkan Seedance di balik adapter video asinkron

Generasi text-to-video biasanya membutuhkan waktu lebih lama daripada permintaan API sinkron biasa. Alur public Seedance API menjelaskan pembuatan tugas yang diikuti oleh pengecekan status atau pengiriman webhook. Modelkan siklus hidup itu secara eksplisit.

export type VideoJobState =
  | "queued"
  | "running"
  | "succeeded"
  | "failed"
  | "cancelled";

export interface VideoJob {
  id: string;
  state: VideoJobState;
  outputUrl?: string;
  errorCode?: string;
}

export interface TextToVideoAdapter {
  createJob(input: {
    prompt: string;
    model: string;
    idempotencyKey: string;
  }): Promise<VideoJob>;

  getJob(jobId: string): Promise<VideoJob>;
}

Adapter harus menerjemahkan field internal stabil milik produk Anda ke payload yang diwajibkan endpoint video saat ini. Simpan parameter khusus provider di dalam adapter itu, bukan membiarkannya bocor ke controller, kode UI, atau skema antrean.

Jangan berasumsi endpoint video adalah /chat/completions, dan jangan berasumsi respons chat membuktikan bahwa rute Seedance yang dipilih tersedia. Konfirmasikan endpoint, alias model, parameter, dan nilai status saat ini di dokumentasi produk atau dashboard pada saat implementasi.

Langkah 5: buat polling aman dan terbatas

Worker video membutuhkan aturan keandalan yang berbeda dari permintaan chat. Polling tanpa henti bukan strategi retry.

import random
import time


TERMINAL_STATES = {"succeeded", "failed", "cancelled"}


def wait_for_video(adapter, job_id: str, deadline_seconds: int = 600):
    started_at = time.monotonic()
    attempt = 0

    while time.monotonic() - started_at < deadline_seconds:
        job = adapter.get_job(job_id)
        if job.state in TERMINAL_STATES:
            return job

        attempt += 1
        delay = min(30, 2 ** min(attempt, 4))
        time.sleep(delay + random.uniform(0, 1))

    raise TimeoutError(f"Video job {job_id} exceeded its processing deadline")

Polling produksi juga harus mematuhi panduan provider dan header Retry-After apa pun. Simpan ID tugas eksternal sebelum polling agar restart worker tidak membuat video duplikat.

Jika webhook tersedia, verifikasi signature, berikan acknowledgement dengan cepat, dan buat handler idempotent. Sebuah webhook dapat dikirim lebih dari sekali atau tiba setelah worker polling telah menyelesaikan tugas.

Langkah 6: tambahkan observabilitas di kedua lapisan

Pantau permintaan gateway dan job video di level produk secara terpisah.

Field Gateway

• lingkungan dan nama layanan
• ID permintaan internal
• rute atau alias model
• status HTTP
• latensi
• jumlah retry
• data penggunaan atau biaya yang terlihat di dashboard

Field job video

• ID job eksternal
• ID user atau workspace
• versi prompt, tanpa mencatat konten prompt sensitif secara default
• model dan mode kapabilitas
• timestamp antrean, mulai, dan selesai
• state terminal dan kode error yang dinormalisasi
• lokasi aset output dan kebijakan retensi

Dasbor adalah titik pemeriksaan operasional bersama. Setelah smoke test dan job video terkontrol pertama, bandingkan log aplikasi dengan catatan penggunaan Flatkey. Selidiki catatan yang hilang, job duplikat, nama model yang tidak terduga, atau perubahan biaya sebelum memperluas traffic.

Langkah 7: gunakan rencana rollout yang dapat dibalik

Mengubah satu base URL itu sederhana. Meluncurkan secara aman tetap memerlukan kontrol.

1. Jalankan smoke test dari lingkungan developer.
2. Jalankan satu job evaluasi Seedance yang tidak sensitif.
3. Konfirmasi penanganan status job, pengambilan aset, dan visibilitas penggunaan.
4. Aktifkan rute untuk akun internal atau persentase traffic yang kecil.
5. Bandingkan tingkat keberhasilan, latensi end-to-end, dan biaya per aset yang selesai.
6. Tingkatkan traffic hanya setelah error budget tetap dapat diterima.
7. Jaga konfigurasi penyedia sebelumnya tetap tersedia sampai kriteria rollback kedaluwarsa.

Tentukan pemicu rollback sebelum peluncuran. Contohnya mencakup error autentikasi yang berulang, tingkat job gagal yang meningkat, job yang macet melewati batas waktu pemrosesan, catatan penggunaan yang hilang, atau kegagalan pengambilan output.

Daftar periksa migrasi

Kesalahan migrasi yang umum

Menganggap kompatibilitas OpenAI sebagai kompatibilitas endpoint universal

Klien yang kompatibel dengan OpenAI dapat menyederhanakan autentikasi dan keluarga permintaan yang didukung. Itu tidak menjamin bahwa setiap operasi multimodal atau video memiliki skema yang sama. Tetap buat adapter video secara eksplisit.

Mengubah key, base URL, model, dan logika worker dalam satu rilis

Itu membuat kegagalan sulit diisolasi. Buktikan koneksi gateway terlebih dahulu, lalu ubah jalur video.

Mengulang pembuatan job tanpa strategi idempotensi

Timeout jaringan dapat terjadi setelah penyedia menerima job. Membuat job lain secara buta dapat menghasilkan dan menagih aset duplikat.

Menggunakan timeout permintaan HTTP sebagai batas waktu video

Permintaan create-job dan siklus hidup pemrosesan video adalah timer yang berbeda. Jaga permintaan pertama tetap singkat, lalu lacak batas waktu asinkron dalam status job yang tahan lama.

Melewati verifikasi dasbor

Respons aplikasi yang berhasil bukanlah pemeriksaan operasional yang lengkap. Pastikan bahwa informasi penggunaan, model, latensi, dan biaya muncul di tempat yang diharapkan tim untuk memantaunya.

FAQ

Can I integrate Seedance by changing only the OpenAI base URL?

Mengubah base URL dapat menyederhanakan lapisan koneksi bersama untuk permintaan OpenAI-compatible yang didukung. Pembuatan video Seedance mungkin masih memerlukan endpoint asinkron khusus dan parameter khusus penyedia. Verifikasi rute saat ini sebelum implementasi.

Apa yang harus tetap tidak berubah selama migrasi?

Jaga agar injeksi secret, penamaan environment, correlation ID, logging, alerting, dan antarmuka video yang menghadap produk tetap stabil. Batasi perubahan khusus penyedia pada konfigurasi dan adapter video.

Mengapa menjalankan chat smoke test untuk produk video?

Smoke test dengan cepat mengisolasi autentikasi gateway, base URL, jaringan, dan Usage Logs dari alur kerja video yang lebih panjang. Ini adalah tes koneksi, bukan tes kemampuan video.

Haruskah saya melakukan polling atau menggunakan webhook untuk penyelesaian video?

Gunakan mekanisme yang didukung oleh API video saat ini dan infrastruktur Anda. Polling lebih sederhana tetapi harus dibatasi dan diberi jeda bertahap. Webhook mengurangi polling tetapi memerlukan verifikasi tanda tangan, idempotency, dan rekonsiliasi untuk event yang terlewat.

Bagaimana cara mencegah job video duplikat?

Buat dan simpan kunci idempotency untuk permintaan produk, simpan external job ID segera, dan buat retry melanjutkan job yang sudah ada setiap kali memungkinkan.

Di mana saya harus membandingkan biaya sebelum rollout?

Tinjau halaman harga Flatkey saat ini, lalu bandingkan biaya per video yang selesai, bukan hanya harga per permintaan atau per detik. Sertakan job yang gagal dan terduplikasi dalam perhitungan.

Bangun batas stabil terlebih dahulu

Migrasi tercepat bukanlah yang mengubah paling sedikit baris pada hari pertama. Migrasi tercepat adalah yang mengurangi perubahan penyedia di masa depan menjadi pembaruan konfigurasi yang terkontrol dan sebuah adapter kecil.

Mulailah dengan satu kunci Flatkey, pindahkan klien bersama ke base URL yang stabil, verifikasi koneksi di Usage Logs, lalu uji alur kerja Seedance saat ini sebagai sistem job asinkron. Saat pemeriksaan lulus, dapatkan kunci dan lakukan rollout dengan metrik yang jelas serta pemicu rollback.