Vercel AI SDK: Sume API 도구 호출로 영상 생성하기

Vercel AI SDK에서 Sume로 영상을 생성하려면, execute 함수가 서버에서 Idempotency-Key와 함께 POST https://api.sume.com/v1/videos를 호출하는 tool()을 정의하고, 영상 대신 Job id를 반환하세요. 영상 생성은 보통 30초에서 몇 분까지 걸리기 때문입니다.

Sume 관련 내용은 영상 생성 (영문), Job과 결과 (영문), TypeScript SDK 페이지에서, AI SDK 관련 내용은 AI SDK 7.x 기준 도구 호출, MCP, experimental_generateVideo 페이지에서 가져왔으며, 모두 2026-09-27에 확인했습니다. 요청 형태 자체는 OpenRouter 호환 영상 API에서 다룹니다.

Sume에서 experimental_generateVideo를 쓸 수 있나요?

직접은 쓸 수 없습니다. experimental_generateVideo()는 영상 모델로 영상을 생성하며(model 파라미터는 VideoModelV4 타입입니다), AI SDK는 영상 생성을 실험적 기능으로 표시합니다. Sume에는 전용 AI SDK 프로바이더가 없으므로, 이 글에서는 직접 작성한 도구에서 일반 HTTPS로 Sume를 호출합니다. 이렇게 하면 model: "sume/auto" 같은 Sume 전용 요청 값도 쓸 수 있습니다.

영상 도구는 어떻게 정의하나요?

도구에는 description, 모델이 읽고 SDK가 모델의 도구 호출을 검증하는 데 쓰는 inputSchema, 그리고 async execute 함수가 있습니다. execute는 두 번째 파라미터로 옵션도 받는데, 여기에는 도구 호출 id와 abort signal이 들어 있습니다.

• 도구 호출 id를 쓰면 도구 호출마다 고유한 Idempotency-Key가 생기므로, 그 호출을 재시도할 때는 같은 키를 다시 씁니다. /v1/videos에서 같은 키로 다시 보내면 새 Job이 아니라 원래 Job이 돌아옵니다.
• model과 prompt가 필수 필드이고, duration(정수 초)과 aspect_ratio는 선택입니다.
• AI SDK 문서에 따르면 도구 코드는 애플리케이션이 실행되는 곳에서 실행되므로, generateText나 streamText는 서버 라우트에서 호출하세요. Sume API 키는 크레딧을 쓰며 브라우저에 안전한 변형이 없습니다. 클라이언트 JavaScript나 NEXT_PUBLIC_* 변수에 절대 넣지 마세요.
• execute에서 던진 오류는 tool-error 콘텐츠 파트로 추가되므로, 멀티 스텝 호출에서는 모델이 그 오류에 대응할 수 있습니다.

import { tool } from "ai";
import { z } from "zod";
export const startVideo = tool({
  description: "Start a Sume video job. Returns a job id; the video takes minutes.",
  inputSchema: z.object({
    prompt: z.string(),
    aspect_ratio: z.string().optional().describe("For example 16:9 or 9:16"),
    duration: z.number().optional().describe("Length in whole seconds"),
  }),
  execute: async (input, { toolCallId, abortSignal }) => {
    const res = await fetch("https://api.sume.com/v1/videos", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.SUME_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": `chat-video-${toolCallId}`,
      },
      body: JSON.stringify({ model: "sume/auto", ...input }),
      signal: abortSignal,
    });
    if (!res.ok) throw new Error(`Sume returned ${res.status}`);
    const job = await res.json();
    return { job_id: job.id, status: job.status };
  },
});

영상을 기다리지 않고 Job id를 반환하는 이유는 무엇인가요?

POST /v1/videos는 즉시 202로 응답하며 id, polling_url, status: "pending"을 돌려줍니다. 영상은 나중에 나오므로 채팅에는 id를 돌려주고, 서버나 두 번째 도구에서 적당한 간격으로 GET /v1/videos/{id}를 읽으세요. 문서는 30초 간격을 제안합니다. 폴링 대신 callback_url(HTTPS)을 보내면, Job이 종료 상태에 도달했을 때 Sume가 서명된 웹훅을 POST합니다. Sume 문서는 전달이 누락되거나 재시도될 때를 대비해 폴링을 계속 쓸 수 있게 두라고 합니다.

채팅에 보여 줄 URL은 어떻게 얻나요?

completed가 되면 unsigned_urls는 GET /v1/videos/{id}/content를 가리키는데, 문서는 이 엔드포인트를 API 키와 함께 호출합니다. 그러니 채팅 UI가 아니라 서버에서 가져오세요. 같은 Job은 GET /v1/jobs/{id}/result에서도 볼 수 있으며, 여기서 result.artifacts[].url은 Sume가 생성 결과물을 돌려주는 형식인 media.sume.com URL입니다. Sume 문서는 그곳의 완료된 Job 아티팩트를 공개 아티팩트로 설명하므로, 채팅에 넘길 URL은 바로 이 URL입니다.

채팅을 중단하면 영상도 취소되나요?

아닙니다. AI SDK는 generateText와 streamText의 abort signal을 도구로 전달하며, 이를 fetch에 넘기면 그 요청이 멈춥니다. Sume Job은 별개입니다. 클라이언트 쪽 타임아웃은 Job을 취소하지 않으며, Job은 계속 실행되고 계속 청구됩니다. Job을 멈추려면 POST /v1/jobs/{id}/cancel을 호출하세요. 취소는 생성 작업이 시작되기 전에만 성공하며, 그 뒤에는 API가 409 job_generation_already_started로 응답합니다. AI 영상 Job을 취소하는 방법을 참고하세요.

대신 Sume의 MCP 도구를 불러올 수 있나요?

네. @ai-sdk/mcp의 createMCPClient에 HTTP 트랜스포트를 url: "https://mcp.sume.com/mcp"와 함께 넘기면 됩니다. HTTP 트랜스포트는 AI SDK가 프로덕션용으로 권장하는 방식입니다. 무인으로 실행되는 서버 코드라면 키를 headers에 넣을 수 있습니다. Sume 문서는 API 키 원격 MCP를 OAuth를 쓰지 않는 자동화를 위한 다른 경로라고 설명합니다. mcpClient.tools()는 서버가 제공하는 모든 도구를 불러오고, Sume의 API 키 세션에는 쓰기·유료 도구가 보입니다. AI SDK는 서버의 annotation을 신뢰할 수 없는 힌트로 취급하며, 도구 허용 목록과 자체 toolApproval 정책을 함께 쓰라고 권합니다. tools()에 schemas를 넘기면 직접 정의한 도구만 가져옵니다. 요청 하나에만 쓴다면 응답이 끝났을 때 클라이언트를 닫으세요.

Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 경로는 아니라고 설명하므로, 클립 하나라면 위의 REST 도구가 더 직접적인 경로입니다.