URL gốc tương thích OpenAI ổn định cho các nhóm sản phẩm Seedance API

Việc chuyển một sản phẩm chuyển văn bản thành video từ cấu hình của nhà cung cấp này sang nhà cung cấp khác không nên đòi hỏi phải viết lại mọi helper xác thực, biến môi trường, quy tắc thử lại và hook quan sát. Mô hình an toàn hơn là tách các phần trong tích hợp của bạn có thể giữ ổn định khỏi các phần đặc thù cho việc tạo video.

Đối với các nhóm đã sử dụng client kiểu OpenAI, Flatkey cung cấp một điểm khởi đầu thực tế: tạo một API key, đặt base URL của client thành https://router.flatkey.ai/v1, chạy một yêu cầu tương thích nhỏ, và xác nhận yêu cầu trong Usage Logs. Điều đó chứng minh lớp kết nối dùng chung trước khi bạn gắn một quy trình làm việc video bất đồng bộ đặc thù của Seedance.

Hướng dẫn này cho thấy cách thực hiện việc chuyển đổi đó một cách có kiểm soát, có thể đảo ngược và dễ kiểm tra.

Câu trả lời nhanh

Một base URL ổn định tương thích OpenAI có thể giảm khối lượng công việc di chuyển cho các phần dùng chung của một tích hợp AI:

• chèn API key
• cấu hình môi trường
• khởi tạo client
• đối chiếu yêu cầu
• chính sách thử lại và timeout
• giám sát mức sử dụng và chi phí

Nó không có nghĩa là mọi nhà cung cấp chuyển văn bản thành video đều dùng cùng một request body hay cùng một endpoint. Tạo video thường cần một luồng bất đồng bộ riêng: tạo job, lưu job ID, poll hoặc nhận webhook, và lấy tài sản cuối cùng.

Vì vậy, mục tiêu triển khai không phải là “ép Seedance đi qua một hình dạng chat-completions.” Mục tiêu là “giữ kết nối gateway ổn định, rồi cô lập bộ chuyển đổi job đặc thù cho video phía sau một giao diện nhỏ.”

Tại sao độ ổn định của base URL lại quan trọng đối với sản phẩm chuyển văn bản thành video

Các lần chuyển đổi nhà cung cấp thường thất bại ở các mối nối quanh lời gọi mô hình, chứ không phải ở một dòng đơn lẻ đặt tên cho mô hình. Một ứng dụng production có thể có API key trong secrets manager, HTTP client trong nhiều dịch vụ, queue worker, webhook handler, audit log, cảnh báo chi tiêu và cài đặt rollback.

Nếu mỗi nhà cung cấp được nối trực tiếp vào tất cả các lớp đó, việc thêm một mô hình video mới sẽ trở thành một thay đổi hạ tầng rộng lớn. Một ranh giới gateway ổn định sẽ giới hạn phạm vi ảnh hưởng.

Kết quả là bề mặt di chuyển nhỏ hơn. Mã sản phẩm của bạn tiếp tục phụ thuộc vào một giao diện nội bộ ổn định trong khi bộ chuyển đổi xử lý các khác biệt trong API video.

Trình tự di chuyển an toàn nhất

Hãy dùng hai bước kiểm tra riêng biệt thay vì cố xác thực toàn bộ đường dẫn video trong một request.

1. Kiểm tra nhanh kết nối: xác minh xác thực, URL gốc tương thích OpenAI, khả năng truy cập mạng, và Usage Logs.
2. Kiểm tra luồng video: xác minh route Seedance hiện tại, các tham số được chấp nhận, các chuyển trạng thái bất đồng bộ, việc phân phối tài sản, và hành vi tính phí.

Sự tách biệt này giúp phân loại lỗi dễ dàng hơn. Nếu kiểm tra nhanh thất bại, vấn đề rất có thể nằm ở thông tin xác thực, cấu hình URL gốc, mạng, hoặc xử lý request dùng chung. Nếu kiểm tra nhanh thành công nhưng job video thất bại, hãy tập trung vào route của model và bộ chuyển đổi video.

Step 1: move the base URL into configuration

Không hardcode URL của nhà cung cấp trong logic ứng dụng. Hãy đưa kết nối gateway vào biến môi trường để quá trình triển khai và rollback không cần thay đổi mã nguồn.

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

Hãy xem giá trị model video như một thiết lập tại thời điểm triển khai. Alias của model và các khả năng được hỗ trợ có thể thay đổi, vì vậy hãy xác nhận route hiện tại trong Flatkey trước khi rollout thay vì sao chép một mã định danh cũ từ bài blog.

Step 2: initialize the existing OpenAI-style client once

Nếu ứng dụng của bạn đã sử dụng OpenAI Python SDK, thì thay đổi kết nối dùng chung này được thiết kế là rất nhỏ.

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"),
)

Cấu hình TypeScript tương đương giữ nguyên ranh giới đó:

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",
});

Điểm quyết định thiết kế quan trọng là các service import một client đã được cấu hình thay vì tự tạo các client riêng theo từng nhà cung cấp trong toàn bộ codebase.

Step 3: run a connection smoke test before touching video jobs

Hướng dẫn khởi đầu nhanh của Flatkey sử dụng một request chat-completions tương thích OpenAI và sau đó yêu cầu bạn xác minh cuộc gọi trong Usage Logs. Hãy dùng bài kiểm tra nhỏ đó để chứng minh lớp tích hợp dùng chung.

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 này không kiểm tra việc tạo video Seedance. Nó xác minh bốn điều kiện tiên quyết mà cả hai luồng đều phụ thuộc vào:

• key có tồn tại và được chấp nhận
• URL gốc là đúng
• ứng dụng có thể kết nối tới router
• request xuất hiện trong dashboard kèm dữ liệu usage

Để xem hướng dẫn chi tiết cho yêu cầu đầu tiên, hãy dùng Seedance API quickstart cho các nhóm sản phẩm.

Bước 4: giữ Seedance phía sau một bộ chuyển đổi video bất đồng bộ

Việc tạo video từ văn bản thường mất nhiều thời gian hơn một yêu cầu API đồng bộ bình thường. Luồng Seedance API công khai mô tả việc tạo tác vụ, sau đó kiểm tra trạng thái hoặc nhận qua webhook. Hãy mô hình hóa vòng đời đó một cách rõ ràng.

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>;
}

Bộ chuyển đổi nên ánh xạ các trường nội bộ ổn định của sản phẩm bạn thành payload mà endpoint video hiện tại yêu cầu. Giữ các tham số chỉ dành cho nhà cung cấp bên trong bộ chuyển đổi đó thay vì để chúng rò rỉ vào controller, mã UI hoặc schema hàng đợi.

Đừng giả định endpoint video là /chat/completions, và cũng đừng giả định một phản hồi chat chứng minh rằng tuyến Seedance đã chọn đang khả dụng. Hãy xác nhận endpoint hiện tại, bí danh model, tham số và các giá trị trạng thái trong tài liệu sản phẩm hoặc bảng điều khiển tại thời điểm triển khai.

Bước 5: làm cho việc polling an toàn và có giới hạn

Một worker video cần các quy tắc độ tin cậy khác với một yêu cầu chat. Polling mãi mãi không phải là chiến lược 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 trong môi trường production cũng nên tôn trọng hướng dẫn của nhà cung cấp và bất kỳ header Retry-After nào. Lưu ID tác vụ bên ngoài trước khi polling để việc khởi động lại worker không tạo ra một video trùng lặp.

Nếu có webhook, hãy xác minh chữ ký, phản hồi nhanh và làm cho handler mang tính idempotent. Một webhook có thể được gửi nhiều lần hoặc đến sau khi worker polling đã hoàn tất tác vụ.

Bước 6: thêm khả năng quan sát ở cả hai lớp

Giám sát riêng yêu cầu gateway và tác vụ video ở cấp sản phẩm.

Các trường của gateway

• môi trường và tên dịch vụ
• ID yêu cầu nội bộ
• tuyến hoặc bí danh model
• mã trạng thái HTTP
• độ trễ
• số lần retry
• dữ liệu sử dụng hoặc chi phí hiển thị trong bảng điều khiển

Các trường của tác vụ video

• ID tác vụ bên ngoài
• ID người dùng hoặc workspace
• phiên bản prompt, mặc định không ghi log nội dung prompt nhạy cảm
• model và chế độ khả năng
• thời điểm vào hàng đợi, bắt đầu và hoàn tất
• trạng thái cuối cùng và mã lỗi đã chuẩn hóa
• vị trí tài sản đầu ra và chính sách lưu giữ

Bảng điều khiển là điểm kiểm tra vận hành chung. Sau bài kiểm tra khói và tác vụ video có kiểm soát đầu tiên, hãy đối chiếu nhật ký ứng dụng với bản ghi sử dụng Flatkey. Điều tra các bản ghi bị thiếu, tác vụ trùng lặp, tên mô hình bất ngờ hoặc thay đổi chi phí trước khi mở rộng lưu lượng.

Bước 7: sử dụng kế hoạch triển khai có thể hoàn nguyên

Việc thay đổi một URL gốc là đơn giản. Nhưng triển khai an toàn vẫn cần các biện pháp kiểm soát.

1. Chạy bài kiểm tra khói từ môi trường nhà phát triển.
2. Chạy một tác vụ đánh giá Seedance không nhạy cảm.
3. Xác nhận xử lý trạng thái tác vụ, truy xuất tài nguyên và khả năng hiển thị mức sử dụng.
4. Bật tuyến cho một tài khoản nội bộ hoặc một phần nhỏ lưu lượng.
5. So sánh tỷ lệ thành công, độ trễ end-to-end và chi phí trên mỗi tài nguyên hoàn thành.
6. Tăng lưu lượng chỉ sau khi ngân sách lỗi vẫn ở mức chấp nhận được.
7. Giữ cấu hình nhà cung cấp trước đó khả dụng cho đến khi tiêu chí hoàn nguyên hết hiệu lực.

Xác định các điều kiện kích hoạt hoàn nguyên trước khi phát hành. Ví dụ gồm lỗi xác thực lặp lại, tỷ lệ tác vụ thất bại tăng cao, tác vụ bị kẹt vượt quá thời hạn xử lý, bản ghi sử dụng bị thiếu hoặc lỗi truy xuất đầu ra.

Danh sách kiểm tra di chuyển

Các lỗi di chuyển thường gặp

Coi khả năng tương thích OpenAI là khả năng tương thích điểm cuối phổ quát

Một client tương thích OpenAI có thể đơn giản hóa xác thực và các nhóm yêu cầu được hỗ trợ. Điều đó không đảm bảo rằng mọi thao tác đa phương thức hoặc video đều có cùng lược đồ. Hãy giữ bộ chuyển đổi video ở dạng tường minh.

Thay đổi khóa, URL gốc, mô hình và logic worker trong cùng một bản phát hành

Điều đó khiến việc cô lập lỗi trở nên khó khăn. Hãy chứng minh kết nối gateway trước, rồi mới thay đổi đường dẫn video.

Thử lại việc tạo tác vụ mà không có chiến lược idempotency

Một lần timeout mạng có thể xảy ra sau khi nhà cung cấp đã chấp nhận tác vụ. Việc tạo một tác vụ khác một cách mù quáng có thể tạo ra và bị tính phí cho một tài nguyên trùng lặp.

Dùng timeout của yêu cầu HTTP làm thời hạn video

Yêu cầu tạo tác vụ và vòng đời xử lý video là hai bộ hẹn giờ khác nhau. Hãy giữ yêu cầu đầu tiên ngắn, sau đó theo dõi thời hạn bất đồng bộ trong trạng thái tác vụ bền vững.

Bỏ qua việc xác minh bảng điều khiển

Phản hồi thành công của ứng dụng không phải là kiểm tra vận hành hoàn chỉnh. Hãy xác nhận rằng thông tin về usage, model, latency và cost xuất hiện ở nơi nhóm mong đợi để theo dõi chúng.

FAQ

Tôi có thể tích hợp Seedance chỉ bằng cách thay đổi base URL của OpenAI không?

Thay đổi base URL có thể đơn giản hóa lớp kết nối dùng chung cho các yêu cầu tương thích OpenAI được hỗ trợ. Việc tạo video bằng Seedance vẫn có thể cần một endpoint bất đồng bộ riêng và các tham số đặc thù của nhà cung cấp. Hãy xác minh route hiện tại trước khi triển khai.

Điều gì nên giữ nguyên trong quá trình di chuyển?

Giữ cho việc tiêm secret, đặt tên môi trường, correlation IDs, logging, alerting và giao diện video hướng đến sản phẩm ổn định. Hạn chế các thay đổi đặc thù của nhà cung cấp ở mức cấu hình và video adapter.

Tại sao lại chạy smoke test chat cho một sản phẩm video?

Smoke test nhanh chóng cô lập xác thực gateway, base URL, mạng và Usage Logs khỏi luồng video dài hơn. Đây là kiểm tra kết nối, không phải kiểm tra khả năng video.

Tôi nên polling hay dùng webhook cho việc hoàn tất video?

Hãy dùng cơ chế được hỗ trợ bởi API video hiện tại và hạ tầng của bạn. Polling đơn giản hơn nhưng phải có giới hạn và back off. Webhook giảm polling nhưng yêu cầu xác minh chữ ký, idempotency và đối soát cho các sự kiện bị bỏ lỡ.

Làm thế nào để ngăn các job video trùng lặp?

Tạo và lưu bền vững một idempotency key cho yêu cầu sản phẩm, lưu ngay external job ID, và để các lần retry tiếp tục job hiện có bất cứ khi nào có thể.

Tôi nên so sánh chi phí ở đâu trước khi triển khai rộng?

Xem lại trang giá của Flatkey hiện tại, sau đó so sánh chi phí trên mỗi video hoàn tất thay vì chỉ giá trên mỗi request hoặc mỗi giây. Bao gồm cả các job thất bại và bị trùng lặp trong phép tính.

Xây dựng ranh giới ổn định trước

Quá trình di chuyển nhanh nhất không phải là quá trình có ít dòng thay đổi nhất trong ngày đầu tiên. Đó là quá trình giảm các thay đổi nhà cung cấp trong tương lai xuống còn một cập nhật cấu hình có kiểm soát và một adapter nhỏ.

Bắt đầu với một Flatkey key, chuyển client dùng chung sang base URL ổn định, xác minh kết nối trong Usage Logs, rồi kiểm tra luồng công việc Seedance hiện tại như một hệ thống job bất đồng bộ. Khi các kiểm tra đạt, lấy một key và triển khai với các chỉ số rõ ràng cùng các ngưỡng kích hoạt rollback.