---
author: OOMOL
author_url: https://oomol.com/ko/about/
title: 이미지 및 동영상 API 연결 가이드
description: OOMOL API key를 설정하고 SDK 또는 HTTP로 모델을 호출하며 비동기 작업과 오류를 처리합니다.
lang: ko
canonical_url: https://oomol.com/ko/docs/image-video-api/
markdown_url: https://oomol.com/ko/docs/image-video-api.md
---

# 이미지 및 동영상 API 연결 가이드

신뢰할 수 있는 백엔드에서 OOMOL Fusion API로 이미지를 생성·편집하고 동영상을 만드세요. 제공업체별로 지원하는 요청과 응답 형식을 유지합니다. 지원 범위는 특정 모델과 작업에 한정되며 제공업체의 모든 API를 포함하지 않습니다.

## API key 만들기

[OOMOL Console](https://console.oomol.com/api-key)에서 개인 API key를 만들고 백엔드에 아래 환경 변수를 설정하세요. OOMOL key를 SDK의 apiKey 또는 HTTP Bearer token으로 사용합니다. 예시에 제공업체 키를 넣을 필요는 없습니다. 브라우저 코드, 공개 저장소, 로그에 키를 포함하지 마세요.

```sh
export FUSION_API_TOKEN="<your-oomol-api-key>"
```

## 엔드포인트 선택

서비스 주소는 [https://fusion-api.oomol.com](https://fusion-api.oomol.com) 입니다. 아래의 전체 Base URL을 버전 경로까지 포함해 사용하세요. Connector 또는 ProjectConnector 주소로 바꾸지 마세요. 유료 요청 전에 모델 제공 여부와 [요금](/ko/pricing/)을 확인하세요.

| 제공업체 | Base URL |
| --- | --- |
| OpenAI Images | `https://fusion-api.oomol.com/v1/provider/openai/v1` |
| Seedream | `https://fusion-api.oomol.com/v1/provider/seedream/api/v3` |
| Seedance | `https://fusion-api.oomol.com/v1/provider/seedance/api/v3` |
| Wanx | `https://fusion-api.oomol.com/v1/provider/wanx/api/v1` |
| Kling | `https://fusion-api.oomol.com/v1/provider/kling/` |
| MiniMax | `https://fusion-api.oomol.com/v1/provider/minimax/` |

## 예시 실행

선택한 제공업체에 필요한 패키지만 설치하세요. 예시를 example.ts로 저장하고 서버 측 TypeScript 환경에서 실행하세요. 표시된 버전은 저장소의 로컬 호환성 테스트 기준이며 모든 SDK 버전을 보장하지 않습니다. 유효한 인증 정보와 사용 가능한 엔드포인트로 실행하면 실제 생성 요청이 전송됩니다.

### OpenAI Images

이미지 생성 및 편집. 다른 OpenAI API는 제외됩니다.

```sh
npm install openai@7.23.0
```

```ts
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FUSION_API_TOKEN,
  baseURL: "https://fusion-api.oomol.com/v1/provider/openai/v1",
  maxRetries: 0,
  timeout: 1_080_000,
});

const result = await client.images.generate({
  model: "gpt-image-2",
  prompt: "A ceramic mug on a wooden table",
  size: "1536x864",
  quality: "medium",
});
console.log(result);
```

### Seedream

이미지 생성, 참조 이미지 및 일부 SSE 출력.

```sh
npm install @volcengine/ark-runtime@1.0.11
```

```ts
import { ArkRuntimeClient } from "@volcengine/ark-runtime";

const client = new ArkRuntimeClient({
  apiKey: process.env.FUSION_API_TOKEN,
  baseURL: "https://fusion-api.oomol.com/v1/provider/seedream/api/v3",
  retryTimes: 0,
  timeout: 125_000,
});

const result = await client.generateImages({
  model: "doubao-seedream-5-0-260128",
  prompt: "A ceramic mug on a wooden table",
  size: "2K",
  response_format: "url",
});
console.log(result);
```

### Seedance

동영상 생성 및 작업 조회.

```sh
npm install @volcengine/ark-runtime@1.0.11
```

```ts
import { ArkRuntimeClient } from "@volcengine/ark-runtime";

const client = new ArkRuntimeClient({
  apiKey: process.env.FUSION_API_TOKEN,
  baseURL: "https://fusion-api.oomol.com/v1/provider/seedance/api/v3",
  retryTimes: 0,
  timeout: 125_000,
});

const task = await client.createContentGenerationTask({
  model: "doubao-seedance-2-0-260128",
  content: [{ type: "text", text: "A boat on the ocean" }],
  duration: 5,
  resolution: "720p",
});
const status = await client.getContentGenerationTask(task.id);
console.log(task.id, status);
```

### Wanx

동영상 생성 및 작업 조회.

```sh
npm install dashscope-sdk-official@1.26.0
```

```ts
import { Configuration, VideoSynthesis } from "dashscope-sdk-official";

const client = new VideoSynthesis(new Configuration({
  apiKey: process.env.FUSION_API_TOKEN,
  basePath: "https://fusion-api.oomol.com/v1/provider/wanx/api/v1",
}));

const task = await client.asyncCall({
  model: "wan3.0-video",
  prompt: "A boat on the ocean",
  resolution: "1080P",
  duration: 5,
});
const status = await client.fetch(task.output.task_id);
console.log(task.output.task_id, status);
```

### Kling

동영상 생성 및 작업 조회.

```sh
npm install ky@1.11.0
```

```ts
import ky from "ky";

const client = ky.create({
  prefixUrl: "https://fusion-api.oomol.com/v1/provider/kling/",
  headers: { Authorization: `Bearer ${process.env.FUSION_API_TOKEN}` },
  retry: 0,
  redirect: "error",
  timeout: 30_000,
});

const task = await client.post("text-to-video/kling-3.0-turbo", {
  json: {
    prompt: "A boat on the ocean",
    settings: { duration: 5, resolution: "720p", aspect_ratio: "16:9" },
  },
}).json<{ data: { id: string } }>();
const status = await client.get("tasks", {
  searchParams: { task_ids: task.data.id },
}).json();
console.log(task.data.id, status);
```

### MiniMax

동영상 생성 및 작업 조회.

```sh
npm install ky@1.11.0
```

```ts
import ky from "ky";

const client = ky.create({
  prefixUrl: "https://fusion-api.oomol.com/v1/provider/minimax/",
  headers: { Authorization: `Bearer ${process.env.FUSION_API_TOKEN}` },
  retry: 0,
  redirect: "error",
  timeout: 30_000,
});

const task = await client.post("v2/video_generation", {
  json: {
    model: "MiniMax-H3",
    content: [{ type: "text", text: "A boat on the ocean" }],
    duration: 5,
    resolution: "768P",
    ratio: "16:9",
  },
}).json<{ task_id: string }>();
const status = await client.get(
  `v2/query/video_generation/${encodeURIComponent(task.task_id)}`,
).json();
console.log(task.task_id, status);
```

## 동영상 결과 조회

동영상 예시는 작업을 만들고 한 번만 조회합니다. 반환된 작업 ID를 저장하세요. 생성 요청 성공은 접수를 뜻하며 영상 완성을 뜻하지 않습니다. 같은 OOMOL 인증 정보로 간격을 두고 종료 상태까지 조회하세요. 성공 또는 실패 시 조회를 멈추고 결과나 오류를 확인하세요. 조회 실패가 생성 실패를 의미하지는 않습니다. 진행 상황을 확인하려고 작업을 다시 만들지 마세요.

## 오류 및 재시도 처리

HTTP 오류와 작업 상태를 모두 확인하세요. 인증 및 잔액 검사에서는 제공업체와 다른 형식의 게이트웨이 오류가 반환될 수 있습니다. 인증 실패는 OOMOL key, 권한·잔액 오류는 계정과 [결제 정보](https://console.oomol.com/billing/recharge), 입력 오류는 모델과 매개변수를 확인하세요. 요청 제한 시 동시 실행 수를 줄이고 응답의 재시도 안내를 따르세요.

생성 요청의 시간 초과, 연결 끊김, 서버 오류로 결과가 불확실할 수 있습니다. 작업 ID, 요청 ID, 오류를 저장하고 가능하면 기존 작업을 조회하세요. 별도의 유료 작업이 생길 수 있으므로 생성 요청을 자동 재전송하지 마세요. OpenAI와 Ark 예시는 SDK 재시도를 끄고 ky는 리디렉션도 끕니다. DashScope는 검증된 SDK 설정을 사용합니다. 앱에서 대기 한도를 설정해도 만료 후 무조건 재전송하지 마세요.

## 파일, 스트리밍 및 결과

업로드, 참조 미디어, 스트리밍 제한은 제공업체별로 다릅니다. OpenAI 예시는 Images API만 다루며 채팅, Responses 등은 포함하지 않습니다. Seedream은 일부 SSE 작업을 지원하고 여기의 OpenAI 이미지 API는 동기 응답입니다. 스트림 이벤트 일부를 받았다고 완료 이벤트를 받은 것은 아닙니다.

반환된 미디어 URL은 별도 클라이언트로 다운로드하고 OOMOL Authorization 헤더를 보내지 마세요. URL이 영구적이라고 가정하지 마세요. 클라이언트 연결을 끊어도 이미 접수된 생성이 취소된다는 보장은 없습니다. 미지원 작업이나 불확실한 결과는 비밀 정보를 제외하고 요청·작업 ID와 함께 [지원팀](mailto:support@oomol.com)에 문의하세요.

[이미지 및 동영상 API 소개](/ko/image-video-api/)로 돌아가기.

## API 레퍼런스

[API 레퍼런스](https://fusion-api.oomol.com/public/docs?lang=en) · [OpenAPI JSON](https://fusion-api.oomol.com/public/openapi.json?lang=en)