DEV Community: Rihpig

Seedance 2.0 API 2026 사용법

Rihpig — Sat, 04 Apr 2026 12:59:17 +0000

요약 (TL;DR)

Seedance 2.0 API는 2026년 4월 2일 Volcengine Ark를 통해 출시되었습니다. POST 요청으로 동영상 생성 작업을 제출한 다음, 상태가 "성공"에 도달할 때까지 GET 엔드포인트를 폴링합니다. 이 API는 텍스트-투-비디오, 이미지-투-비디오, 첫/마지막 프레임 제어, 다중 모드 참조, 원본 오디오 생성을 지원합니다. 5초 길이의 1080p 동영상은 대략 $0.93의 비용이 듭니다. 동영상은 24시간 이내에 다운로드해야 하며, 이후에는 URL이 만료됩니다.

지금 Apidog 사용해 보기

Hypereal AI

Hypereal AI 사용해 보기

소개

2026년 4월 2일, ByteDance의 Volcengine Ark 플랫폼은 공식 Seedance 2.0 API를 출시했습니다. 이 날짜 전까지는 Seedance 2.0 동영상을 생성하려면 웹 콘솔만 사용해야 했습니다. 본 문서는 개발자가 실제 API를 프로그래밍 방식으로 호출하는 방법을 다룹니다.

💡 비동기 작업 패턴: POST로 작업을 생성 → 작업 ID 반환 → GET 엔드포인트 폴링. 실제 배포 전 Apidog 테스트 시나리오로 전체 워크플로를 시뮬레이션하세요. POST 제출, 작업 ID 추출, GET 폴링, 최종 동영상 URL 확인까지 아래 Apidog 섹션의 단계를 따라 실습할 수 있습니다.

이 문서에서는 입력 유형, 가격 계산, 실무 오류 처리까지 실전 개발에 필요한 내용을 다룹니다.

Seedance 2.0이란 무엇인가요?

Seedance 2.0은 ByteDance의 동영상 생성 모델입니다. Volcengine Ark에서 doubao-seedance-2-0-260128 (표준) 및 doubao-seedance-2-0-fast-260128 (빠른 저품질) 모델 ID로 사용합니다.

지원 입력:

텍스트-투-비디오, 이미지-투-비디오
첫/마지막 프레임 제어: 두 개의 이미지를 북엔드로 지정
다중 모드 참조: 이미지/동영상/오디오 복합 입력
원본 오디오 생성: 대화, 효과음, 음악 등
8개+ 언어 립싱크
자연어로 카메라 움직임 제어 (예: 돌리, 트래킹)
최대 15초, 최대 2K 해상도, 24fps, 1:1~21:9 화면비 지원

무엇이 바뀌었나: 가이드 vs 공식 API

2026년 2월 이전 가이드는 Seedance 2.0 웹 콘솔 사용법만 제공했습니다.

2026년 4월부터는 API로 동영상 파이프라인을 자동화하고, 어떤 언어에서도 Seedance를 자체 시스템에 통합할 수 있습니다. 본 문서는 개발자 중심의 자동화 사용법에 집중합니다.

선행 조건

volcengine.com에서 Volcengine 계정 생성

콘솔에서 API 키 발급:

https://console.volcengine.com/ark/region:ark+cn-beijing/apikey

환경 변수로 설정:
```
export ARK_API_KEY="your-api-key-here"
```
모든 API 요청의 Authorization 헤더에 사용:
```
Authorization: Bearer YOUR_ARK_API_KEY
```
신규 계정은 1080p 15초 동영상 약 8개 분량의 무료 체험 크레딧 제공

텍스트-투-비디오: 첫 번째 요청

모든 요청의 기본 URL:

https://ark.cn-beijing.volces.com/api/v3

cURL 예제

curl -X POST "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "A golden retriever running through a sunlit wheat field, wide tracking shot, cinematic"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5,
    "watermark": false
  }'

응답:

{"id": "cgt-2025xxxxxxxx-xxxx"}

Python 예제 (공식 SDK)

SDK 설치:
```
pip install volcenginesdkarkruntime
```

작업 제출:

import os
from volcenginesdkarkruntime import Ark

client = Ark(api_key=os.environ.get("ARK_API_KEY"))

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "A golden retriever running through a sunlit wheat field, wide tracking shot, cinematic"
        }
    ],
    resolution="1080p",
    ratio="16:9",
    duration=5,
    watermark=False,
)

print(resp.id)

작업 ID는 폴링에 사용합니다.

비동기 작업 패턴: 제출, 폴링, 다운로드

동영상 생성은 즉시 완료되지 않습니다. 5초 1080p 기준 60~120초 소요.

상태 수명주기:

queued -> running -> succeeded
                  -> failed
                  -> expired
                  -> cancelled

queued/running이 아닌 상태가 될 때까지 폴링합니다.

전체 Python 폴링 루프

import os
import time
import requests
from volcenginesdkarkruntime import Ark

client = Ark(api_key=os.environ.get("ARK_API_KEY"))

# Step 1: 작업 제출
resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {"type": "text", "text": "Aerial shot of a mountain lake at sunrise, slow dolly forward"}
    ],
    resolution="1080p",
    ratio="16:9",
    duration=5,
    watermark=False,
)

task_id = resp.id
print(f"Task submitted: {task_id}")

# Step 2: 폴링 (지수 백오프)
wait = 10
while True:
    result = client.content_generation.tasks.get(task_id=task_id)
    status = result.status
    print(f"Status: {status}")

    if status == "succeeded":
        video_url = result.content.video_url
        print(f"Video URL: {video_url}")
        break
    elif status in ("failed", "expired", "cancelled"):
        print(f"Task ended with status: {status}")
        break

    time.sleep(wait)
    wait = min(wait * 2, 60)

# Step 3: 성공 시 동영상 다운로드
if status == "succeeded":
    response = requests.get(video_url, stream=True)
    with open("output.mp4", "wb") as f:
        for chunk in response.iter_content(chunk_size=8192):
            f.write(chunk)
    print("Downloaded: output.mp4")

지수 백오프는 API 부하 방지에 필수입니다. 60초 상한 권장.

이미지-투-비디오 (I2V): 정지 이미지 애니메이션화

content 배열에 image_url 객체 추가. 이미지는 첫 프레임이 됩니다.

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "The woman slowly turns her head and smiles at the camera"
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/portrait.jpg"}
        }
    ],
    ratio="adaptive",
    duration=5,
    watermark=False,
)

ratio를 "adaptive"로 설정하면 입력 이미지 비율에 맞춰 생성
각 이미지는 30MB 미만, 요청당 최대 9개까지

첫 프레임과 마지막 프레임: 시작점과 끝점 제어

첫/마지막 프레임 이미지를 순서대로 전달하면, 중간 동작을 자동 생성합니다.

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "The flower blooms from bud to full open, macro lens, soft light"
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/flower-bud.jpg"}
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/flower-open.jpg"}
        }
    ],
    ratio="adaptive",
    duration=8,
    watermark=False,
)

두 이미지: 첫 프레임, 마지막 프레임으로 해석
return_last_frame: true 사용 시, 마지막 프레임 이미지를 추가로 반환 (시퀀스 연결에 활용)

다중 모드 참조: 이미지, 동영상, 오디오 결합

content 배열에 이미지, 동영상, 오디오를 복합 입력으로 제공할 수 있습니다.

이미지: 최대 9개 (각 30MB 이하)
동영상: 최대 3개 (각 2~15초, 50MB 이하)
오디오: 최대 3개 (MP3, 각 15MB 이하)

예시:

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "Match the visual style of the reference clip and add the provided background audio"
        },
        {
            "type": "image_url",
            "image_url": {"url": "https://example.com/style-reference.jpg"}
        },
        {
            "type": "video_url",
            "video_url": {"url": "https://example.com/motion-reference.mp4"}
        },
        {
            "type": "audio_url",
            "audio_url": {"url": "https://example.com/background-music.mp3"}
        }
    ],
    duration=10,
    ratio="16:9",
    watermark=False,
)

동영상 참조를 추가하면 V2V 요금이 적용 (백만 토큰당 $3.90)

원본 오디오 생성

generate_audio: true 옵션으로 동영상과 동기화된 오디오를 생성합니다.

대화, 효과음, 주변음, 음악, 립싱크(8개+ 언어) 지원.

resp = client.content_generation.tasks.create(
    model="doubao-seedance-2-0-260128",
    content=[
        {
            "type": "text",
            "text": "A street musician plays guitar outside a cafe in Paris, crowds passing by, city sounds"
        }
    ],
    resolution="1080p",
    ratio="16:9",
    duration=10,
    generate_audio=True,
    watermark=False,
)

오디오 생성은 무음 동영상보다 토큰 소모량이 소폭 증가합니다. 비용 계산에 반영하세요.

해상도, 비율 및 길이 제어

resolution: "480p", "720p", "1080p", "2K" (기본: 1080p)
ratio: "16:9", "9:16", "4:3", "3:4", "21:9", "1:1", "adaptive"
duration: 4~15 (초, 기본: 5)

빠른 모델(doubao-seedance-2-0-fast-260128)은 프로토타입/프롬프트 반복에, 표준 모델은 최종 출력에 권장.

Seedance 2.0은 오디오-비디오 공동 생성, 프레임 제어, 다중 모드 입력이 필요할 때 가장 적합합니다.

응답에서 비용 확인하기

성공 응답의 usage 필드를 확인하세요:

{
  "usage": {
    "completion_tokens": 246840,
    "total_tokens": 246840
  }
}

토큰 수는 동영상 길이와 해상도에 비례
1080p 기준: 5초 ≈ 102,960 토큰, 15초 ≈ 309,000 토큰
T2V/I2V: 백만 토큰당 46위안(약 $6.40), V2V: 28위안(약 $3.90)

예상 비용:

5초 1080p: $0.93
10초 1080p: $1.32
15초 1080p: $1.97

completion_tokens × 토큰 단가로 애플리케이션별 비용 추적 시스템을 구축하세요.

중요: 24시간 이내에 동영상을 다운로드하세요

응답의 video_url은 24시간 후 만료됩니다.

상태가 succeeded로 바뀌자마자 즉시 파일을 자체 저장소에 다운로드하세요.
execution_expires_after는 작업 기록(48시간) 기준이지만, 동영상 URL은 24시간 후 만료됩니다.
작업 기록은 7일까지만 API에서 조회 가능

Apidog로 Seedance API를 테스트하는 방법

비동기 패턴에서는 연속적 요청/응답 흐름이 필요합니다. Apidog 테스트 시나리오로 아래와 같이 구현하세요.

실습 단계

1단계: 테스트 시나리오 생성

Apidog 테스트 모듈 → "Seedance 2.0 동영상 생성" 새 시나리오
환경 변수 ARK_API_KEY 등록, {{ARK_API_KEY}}로 참조

2단계: 제출 요청 추가

POST: https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks
Authorization: Bearer {{ARK_API_KEY}}
JSON 본문에 모델/컨텐츠 입력
변수 추출: JSONPath $.id → 환경 변수 TASK_ID 저장

3단계: 대기 프로세서 추가

30초 Wait 프로세서 삽입 (처리 시간 보장)

4단계: For 루프에 폴링 요청 추가

최대 20회 반복 For 루프
루프 내:
1. GET: https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/{{TASK_ID}}
2. 10초 Wait
3. Break If: $.status == "succeeded" 또는 $.status == "failed"

5단계: 어설션 추가

루프 종료 후:
- $.status가 "succeeded"
- $.content.video_url이 비어 있지 않음

Apidog는 각 단계, 작업 ID, 폴링 응답, 어설션 결과까지 전체 리포트를 제공합니다.

cURL 명령도 Apidog 시나리오에 직접 Import하여 빠르게 테스트할 수 있습니다.

가격 분석: 10초 동영상의 비용

Seedance API는 토큰 기반 과금제를 사용합니다.

| 작업 유형 | 요금 (100만 토큰당) |
|---|---|
| 1080p T2V / I2V | 46 위안 (약 $6.40) |
| V2V (동영상 참조 입력) | 28 위안 (약 $3.90) |

길이	대략적인 토큰 수	비용 (T2V/I2V)
5초	~103,000	~$0.66 위안 / ~$0.93
10초	~206,000	~$9.48 위안 / ~$1.32
15초	~309,000	~$14.21 위안 / ~$1.97

신규 계정: 15초 동영상 약 8개 분량 무료 크레딧 제공
저해상도(480p)로 개발, 최종 결과만 고해상도 사용 권장

일반적인 오류 및 해결 방법

429 Too Many Requests

동시 작업 수 초과 시 발생
지수 백오프(10초→20→40→60초 상한)로 재시도

status: "failed"

안전 필터 위반, 파일 손상/과대용량, 유효하지 않은 파라미터
입력 및 프롬프트 재확인 후 재시도

status: "expired"

대기열 체류 시간 초과
재시도 필요, 복구 불가

video_url 403 오류

24시간 다운로드 제한 초과
동일 파라미터+시드로 재생성

시드 재현성

이전 응답의 seed 값 재사용 시 동일 결과 근접 재현 가능

결론

Seedance 2.0 API는 동영상 생성 자동화에 최적화된 강력한 모델 접근을 제공합니다.

비동기 패턴: POST 제출 → 폴링 → 즉시 다운로드
다중 모드 입력, 오디오-비디오 동시 생성, 프레임 제어 등 고급 기능 지원

프로덕션 전 Apidog 테스트 시나리오로, 폴링 로직/변수 추출/URL 만료 문제를 사전에 검증하세요.

자주 묻는 질문

Q: doubao-seedance-2-0-260128과 doubao-seedance-2-0-fast-260128의 차이점은?

표준 모델: 고품질, 프로덕션 기본값
빠른 모델: 저품질, 빠른 처리, 프롬프트 반복에 활용

Q: 중국 외 지역 사용 가능?

엔드포인트는 베이징. 해외에서도 호출 가능(지연 증가).
계정/지역 제한은 Volcengine 약관 참고

Q: 여러 클립을 긴 동영상으로 연결하려면?

return_last_frame: true 사용 → 마지막 프레임 이미지를 다음 요청의 첫 프레임으로
반복 생성 후, 동영상 편집 라이브러리로 연결

Q: 원본 오디오 생성 비용은?

오디오-비디오 공동 생성으로 토큰 소모 소폭 증가.
generate_audio: true 옵션 시 completion_tokens가 다소 증가

Q: 폴링 대신 웹훅 사용 가능?

네, 제출 시 callback_url 매개변수 추가
상태 변화시 결과를 해당 URL로 POST

Q: 9개 이미지 제한 초과 시?

400 유효성 오류 반환
이미지 수를 9개 이하로 제한

Q: 시드 매개변수가 완전한 재현 보장?

동일 파라미터+모델 버전이면 근접 재현
서버 모델 업데이트 등 외부 요인 영향 가능

Q: 여러 작업 비용 추적은?

각 응답의 completion_tokens × 토큰 단가
DB에 기록하여 자체 비용 추적 시스템 구축
별도 API 비용 대시보드는 없음

추가 자동화 실습, 실전 API 테스트, 반복적인 워크플로 구현에는 Apidog 활용을 권장합니다.

Grok 텍스트 비디오 API 사용법 완벽 가이드

Rihpig — Fri, 03 Apr 2026 08:42:10 +0000

요약

Grok 텍스트-투-비디오 API는 텍스트 프롬프트로 비디오를 생성합니다. POST /v1/videos/generations를 호출하면 바로 request_id를 받고, 상태가 "done"이 될 때까지 GET /v1/videos/{request_id}로 폴링합니다. 모델은 grok-imagine-video이며, 480p 기준 초당 $0.05부터 과금됩니다. xAI Python SDK는 폴링을 자동화합니다.

지금 Apidog을 사용해보세요

소개

xAI는 2026년 1월 한 달간 12억 개의 비디오를 생성했습니다. 이는 Grok 텍스트-투-비디오 API가 출시된 첫 달의 기록입니다. 같은 달, Artificial Analysis 텍스트-투-비디오 리더보드 1위도 차지했습니다. 이는 인프라의 대규모 검증을 의미합니다.

이 가이드는 첫 요청 생성부터 결과 폴링, 매개변수 조정, 프롬프트 최적화, 참조 이미지 활용, 기존 비디오 확장/편집, 텍스트-투-비디오 적합성 판단까지 실무에 필요한 모든 단계를 다룹니다.

💡 API는 비동기식입니다. 프론트엔드가 비디오 준비를 기다릴 수 없으므로, 테스트마다 크레딧을 소진하지 않고 폴링 흐름을 개발할 수단이 필요합니다. Apidog의 Smart Mock을 사용하면 생성/폴링 엔드포인트를 모두 모의할 수 있어 백엔드가 없어도 비디오 플레이어 UI 개발이 가능합니다. 아래 테스트 섹션을 참고해 Apidog을 무료로 다운로드해보세요.

Grok 텍스트-투-비디오 API란?

Grok 텍스트-투-비디오 API는 https://api.x.ai에서 제공하는 xAI 미디어 생성 API입니다. 텍스트 프롬프트만으로 grok-imagine-video 모델이 짧은 비디오 클립을 생성합니다. 별도의 원본 이미지는 필요 없습니다.

또한 동기식 이미지 생성(POST /v1/images/generations, 모델 grok-imagine-image, 이미지당 $0.02)과 비디오 확장·편집용 엔드포인트도 함께 제공됩니다.

텍스트-투-비디오와 이미지-투-비디오는 근본적으로 다릅니다. 텍스트-투-비디오는 오로지 프롬프트 설명에 따라 장면, 움직임, 스타일을 모두 생성합니다. 원본 이미지를 애니메이션화하고 싶다면 Grok 이미지-투-비디오 API 가이드를 참고하세요.

텍스트-투-비디오 생성 구조 (비동기 패턴)

비디오 생성은 몇 초~몇 분이 걸릴 수 있으므로 비동기 패턴을 사용합니다.

흐름 요약:

프롬프트와 함께 POST 요청.
즉시 request_id 반환(1초 이내).
xAI 서버에서 비디오 생성.
해당 request_id로 GET 폴링.
status가 "done"이 되면 비디오 URL 제공.

비동기 패턴은 HTTP 연결을 짧게 유지하고, 원하는 주기로 진행 상황 확인이 가능합니다. 프론트엔드는 결과를 기다리며 로딩 상태를 처리해야 합니다.

사전 준비

xAI 계정: console.x.ai에서 가입
API 키: xAI 콘솔에서 생성 후 안전하게 보관(모든 요청에 Bearer 토큰으로 사용)

환경 변수로 관리하세요:

export XAI_API_KEY="your_api_key_here"

Python SDK 설치(선택):

pip install xai-sdk

첫 텍스트-투-비디오 요청

curl 사용 예시

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A golden retriever running through autumn leaves in slow motion, cinematic lighting"
  }'

응답 예시:

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

Python (requests) 예시

import requests
import os

API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

payload = {
    "model": "grok-imagine-video",
    "prompt": "A golden retriever running through autumn leaves in slow motion, cinematic lighting"
}

response = requests.post(
    f"{BASE_URL}/v1/videos/generations",
    headers=headers,
    json=payload
)

data = response.json()
request_id = data["request_id"]
print(f"Generation started. Request ID: {request_id}")

비디오 결과 폴링

request_id를 받으면, 상태가 "done"이 될 때까지 GET /v1/videos/{request_id}로 폴링합니다.

"processing": 생성 중
"done": 완료(비디오 URL 제공)
"failed": 실패

Python 폴링 루프 예시:

import requests
import time
import os

API_KEY = os.environ["XAI_API_KEY"]
BASE_URL = "https://api.x.ai"

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

def poll_video(request_id: str, interval: int = 5, max_attempts: int = 60) -> dict:
    url = f"{BASE_URL}/v1/videos/{request_id}"
    for attempt in range(max_attempts):
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")
        progress = data.get("progress", 0)
        print(f"시도 {attempt + 1}: status={status}, progress={progress}%")
        if status == "done":
            return data
        elif status == "failed":
            raise RuntimeError(f"비디오 생성 실패: {data}")
        time.sleep(interval)
    raise TimeoutError(f"{max_attempts}번의 시도 후에도 비디오가 준비되지 않았습니다.")

def generate_video(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/v1/videos/generations",
        headers={**headers, "Content-Type": "application/json"},
        json={"model": "grok-imagine-video", "prompt": prompt}
    )
    request_id = response.json()["request_id"]
    print(f"요청 ID: {request_id}")
    result = poll_video(request_id)
    video_url = result["video"]["url"]
    print(f"비디오 준비 완료: {video_url}")
    return video_url

video_url = generate_video(
    "A timelapse of a city skyline at sunset transitioning to night, aerial view"
)

폴링 완료 응답 예시:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "progress": 100,
  "usage": {
    "cost_in_usd_ticks": 500000000
  }
}

xAI Python SDK로 간소화

SDK는 폴링을 자동으로 처리합니다.

from xai_sdk import Client
import os

client = Client(api_key=os.environ["XAI_API_KEY"])
result = client.video.generate(
    model="grok-imagine-video",
    prompt="A golden retriever running through autumn leaves in slow motion",
    duration=8,
    resolution="720p",
    aspect_ratio="16:9"
)

print(f"비디오 URL: {result.video.url}")
print(f"지속 시간: {result.video.duration}초")

재시도, 진행상황, 간격 제어가 필요하면 직접 원시 HTTP 요청을 사용하세요.

효과적인 비디오 프롬프트 작성법

상세하고 구조화된 프롬프트가 고품질 비디오를 만듭니다.

장면 설명: 주제와 배경을 구체적으로 작성

움직임: 무엇이 어떻게 움직이는지 명확히

카메라 스타일: "클로즈업", "트래킹 샷", "드론 뷰" 등

조명·분위기: "골든 아워", "네온 불빛", "안개 낀 아침" 등

스타일 참조: "시네마틱", "애니메이션" 등 병행 가능

구조 예시:

A lone astronaut floats past the International Space Station,
tether drifting behind them. The camera tracks slowly
alongside, showing Earth below. Cinematic, IMAX quality,
warm sunrise light reflecting off the visor.

해상도, 지속 시간, 화면 비율 제어

duration

"duration": 10

1~15초, 기본 6초 (길수록 비용 증가)

resolution

"resolution": "720p"

"480p"(기본), "720p" 두 가지

aspect_ratio

"aspect_ratio": "9:16"

비율	용도
16:9	데스크톱, YouTube, 프레젠테이션(기본)
9:16	TikTok, Instagram Reels, 모바일
1:1	Instagram 피드, 소셜 카드
4:3	클래식 비디오, 프레젠테이션
3:4	세로 모바일 콘텐츠
3:2	표준 사진 비율
2:3	세로 사진

전체 매개변수 예시:

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "A coastal town at dawn, waves breaking gently on a rocky shore",
    "duration": 10,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

비디오 스타일을 안내하는 참조 이미지 사용

reference_images 파라미터에 최대 7개의 이미지 URL 배열을 전달하면, 생성 비디오의 시각 스타일·톤을 보정할 수 있습니다.

{
  "model": "grok-imagine-video",
  "prompt": "A coastal town at dawn, waves breaking gently on a rocky shore",
  "reference_images": [
    {"url": "https://example.com/my-style-reference.jpg"},
    {"url": "https://example.com/color-palette-reference.jpg"}
  ]
}

팁: 비슷한 미학의 이미지 세트를 사용하세요. 서로 너무 다른 이미지는 결과를 불안정하게 만듭니다.

참조 이미지는 프롬프트를 보완할 뿐, 주제가 되지는 않습니다.

이미지-투-비디오와는 달리, 참조 이미지를 쓸 때도 장면은 프롬프트가 결정합니다.

생성 비디오 확장 및 편집

xAI는 생성된 비디오를 다루기 위한 두 가지 엔드포인트를 제공합니다.

비디오 확장

POST /v1/videos/extensions

기존 비디오의 request_id와 새로운 프롬프트를 전달해 장면을 추가합니다.

15초 제한을 우회해 더 긴 시퀀스 생성에 유리합니다.

비디오 편집

POST /v1/videos/edits

생성된 비디오를 텍스트 지침에 따라 수정(스타일 변경, 장면 수정, 효과 적용 등)

두 엔드포인트 모두 request_id 반환 및 폴링 패턴은 동일합니다.

API 응답에서 비용 확인

모든 완료된 응답에는 usage.cost_in_usd_ticks가 포함됩니다.

"usage": {
  "cost_in_usd_ticks": 500000000
}

USD 변환: 10,000,000으로 나누세요.

cost_in_usd = result["usage"]["cost_in_usd_ticks"] / 10_000_000
print(f"비용: ${cost_in_usd:.4f}")
# 출력: Cost: $0.0500

가격표:

해상도	초당 가격	10초 클립
480p	$0.05	$0.50
720p	$0.07	$0.70

응답의 cost_in_usd_ticks를 기록하면, 별도의 결제 API 없이도 사용량 대시보드를 구축할 수 있습니다.

Apidog로 Grok 비디오 API 테스트하는 방법

비동기 폴링 패턴은 프론트엔드 테스트에 부담을 줍니다. 실제 API 호출마다 비용과 시간이 들기 때문입니다. Apidog의 Smart Mock 기능을 활용하면 이 과정을 효율적으로 자동화할 수 있습니다.

사용 사례 1: 프론트엔드 개발용 Smart Mock

Apidog의 Smart Mock으로 두 엔드포인트의 스키마를 정의하고, 현실적인 가짜 응답을 즉시 받을 수 있습니다.

생성 엔드포인트 모의:

프로젝트에 POST /v1/videos/generations 엔드포인트 생성
응답 스키마: 단일 request_id 문자열 필드
Smart Mock이 자동으로 UUID 반환

폴링 엔드포인트 모의:

GET /v1/videos/{request_id} 생성
응답 스키마: status, video.url, video.duration, progress, usage.cost_in_usd_ticks 등 포함
"status": "done" 및 플레이스홀더 MP4 URL 반환

예시 모의 응답:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/mock-video-12345.mp4",
    "duration": 8,
    "respect_moderation": true
  },
  "progress": 100,
  "usage": {
    "cost_in_usd_ticks": 400000000
  }
}

프론트엔드 개발자는 이 모의 서버로 전체 UI를 구축/테스트할 수 있습니다. 모의 응답을 "failed"로 바꿔 오류 상태도 테스트 가능하며, 실제 API 크레딧은 소모되지 않습니다.

사용 사례 2: 폴링 루프 테스트 시나리오

Apidog의 테스트 시나리오로 생성-폴링 전체 흐름을 자동 검증할 수 있습니다.

생성 요청:
- POST /v1/videos/generations 추가
- 후처리기로 응답 $.request_id를 videoRequestId 변수에 저장
폴링 루프:
- GET /v1/videos/{{videoRequestId}}
- 중단 조건: response.body.status == "done"
- 반복 사이 5초 대기
결과 확인:
- 최종 GET의 $.video.url이 비어 있지 않은지 Assertion 처리

이 방식으로 폴링 로직이 변경될 때마다 자동 회귀 테스트가 가능합니다.

텍스트-투-비디오 vs 이미지-투-비디오: 선택 기준

두 모드 모두 grok-imagine-video 모델을 사용하지만 목적이 다릅니다.

텍스트-투-비디오 사용 사례:

개념/스크립트 기반 원본 콘텐츠 생성
모델이 장면을 창의적으로 생성
사용자 프롬프트 입력 중심
원본 이미지가 필요 없는 경우

이미지-투-비디오 사용 사례:

제품 사진, 일러스트, 브랜드 자산 등에서 애니메이션화
기존 이미지의 세부 요소 유지 필요
연속 이미지의 일관된 애니메이션
직접 만든 이미지나 사진을 활용

핵심 차이: 텍스트-투-비디오는 ‘창조’, 이미지-투-비디오는 ‘애니메이션화’입니다.

자세한 내용은 Grok 이미지-투-비디오 API 가이드 참고.

입력 유형에 따라 런타임에서 두 엔드포인트를 분기할 수 있습니다.

일반적인 오류 및 해결 방법

401 권한 없음: API 키 누락/만료/형식 오류. Authorization 헤더 형식 및 키 활성 여부 확인.
429 너무 많은 요청: 속도 제한. 분당 60회, 초당 1회 이하로 폴링 간격(최소 5초) 유지.
폴링 status: "failed": 프롬프트가 검열에 걸림. respect_moderation이 true인지 확인하고 프롬프트 수정.
비디오 URL 404: 비디오 URL은 임시. 생성 직후 바로 다운로드 필요.
빈/정지 비디오: 모호한 프롬프트/움직임 언어 부족. 명확한 움직임, 방향, 속도 명시.
느린 폴링: 720p/긴 비디오는 생성 시간이 더 걸림. 개발/테스트엔 480p+짧은 duration 권장.

결론

Grok 텍스트-투-비디오 API는 프롬프트 → 비디오까지의 워크플로우를 간단히 구현할 수 있게 해줍니다. 폴링 비동기 패턴만 정확히 구현하면, 나머지(지속 시간/해상도/화면비율/참조 이미지 등)는 쉽게 조정 가능합니다.

프로덕션에서는 cost_in_usd_ticks로 비용 추적을 반드시 추가하세요.

개발 중엔 Apidog에서 엔드포인트를 모의해 프론트엔드가 대기 없이 개발할 수 있게 하세요.

통합 단계에서는 테스트 시나리오로 폴링 로직의 신뢰성을 확보하세요.

Grok 비디오 API용 모의 서버 및 자동화 테스트 시나리오를 구축하려면 Apidog을 지금 무료로 사용해보세요.

자주 묻는 질문

Q. 텍스트-투-비디오 생성에는 어떤 모델 이름을 사용해야 하나요?

A. grok-imagine-video를 사용하세요. 이는 /v1/videos/generations의 model 필드에 필요합니다.

Q. 비디오 생성에는 얼마나 걸리나요?

A. 480p 짧은 클립은 30초 내외, 720p 긴 클립은 수 분 소요. 폴링 주기는 5~10초 간격 권장.

Q. 15초보다 긴 비디오를 생성할 수 있나요?

A. 단일 요청으론 불가. 최대 duration 15초. 더 길게하려면 POST /v1/videos/extensions로 이어붙이세요.

Q. 생성된 비디오는 어떻게 다운로드하나요?

A. 폴링 완료 응답의 result.video.url을 사용해 즉시 MP4로 저장하세요. URL은 임시입니다.

Q. 프롬프트가 콘텐츠 검열에 걸리면?

A. 작업은 "failed" 상태로 종료되고, respect_moderation이 true로 표시됨. 프롬프트 수정 후 재시도.

Q. 비디오 API 무료 등급이 있나요?

A. 초당 과금 방식이며, 무료 등급은 없습니다. 신규 계정 크레딧 제공 여부는 console.x.ai에서 확인.

Q. reference_images와 원본 이미지 시작 방식 차이?

A. 참조 이미지는 스타일 가이드만 가능, 주제가 되지 않음. 이미지-투-비디오의 원본 이미지는 실제 첫 프레임이 됨.

Q. 크레딧을 쓰지 않고 폴링 루프 테스트하려면?

A. Apidog의 Smart Mock으로 생성/폴링 엔드포인트 모두 모의. "processing"/"done" 상태별 응답을 설정해 실제 API 없이 폴링 코드 검증 가능.

Grok 이미지-비디오 API 사용법 (단계별 가이드)

Rihpig — Fri, 03 Apr 2026 08:36:38 +0000

세 줄 요약

그록 이미지-투-비디오 API는 grok-imagine-video 모델을 사용하여 정적 이미지를 비디오 클립으로 애니메이션화합니다. 이미지 URL, 프롬프트 및 선택적 설정을 https://api.x.ai/v1/videos/generations로 POST하면 API가 즉시 request_id를 반환합니다. 이후 GET /v1/videos/{request_id}로 폴링하여 status가 "done"이 될 때까지 상태를 확인합니다. 비디오 재생 시간은 1~15초 지정 가능하며, 480p 출력 기준 초당 0.05달러부터 과금됩니다.

Apidog를 지금 사용해보세요

소개

2026년 1월 28일, xAI는 grok-imagine-video 모델을 공개 API로 출시했습니다. 첫 달에만 12억 개의 비디오가 생성되었고, Artificial Analysis 텍스트-투-비디오 순위표 1위를 차지했습니다. 이미지-투-비디오는 사진과 설명 프롬프트를 전달하면 이미지를 짧은 비디오(MP4)로 자동 애니메이션화합니다.

이 API는 작업 제출 후 완료를 폴링하는 비동기 흐름을 사용합니다. 첫 POST가 200 OK를 반환해도, 실제로는 폴링 루프에서 "processing", "done", "failed" 상태 처리가 올바르게 작동해야 통합이 완성됩니다.

Apidog의 테스트 시나리오(Test Scenarios)는 /v1/videos/generations로 POST → request_id 추출 → 폴링 및 완료 확인 → 비디오 URL 검증의 전체 시퀀스를 자동화할 수 있습니다. 아래 실습을 진행하려면 Apidog를 무료로 다운로드하십시오.

그록 이미지-투-비디오 API란 무엇인가요?

그록 이미지-투-비디오 API는 xAI의 비디오 생성 솔루션입니다. grok-imagine-video 모델은 제공된 이미지를 시작 프레임으로 받아, 프롬프트에 따라 자연스러운 움직임을 생성합니다.

API 엔드포인트:

POST https://api.x.ai/v1/videos/generations

인증: Bearer 토큰 사용

Authorization: Bearer YOUR_XAI_API_KEY

API 키는 xAI 콘솔에서 발급받을 수 있습니다. 동일한 엔드포인트로 텍스트-투-비디오(이미지 없이), 비디오 확장, 편집도 지원합니다.

이미지-투-비디오 프로세스 작동 방식

image 매개변수: 출력 비디오의 첫 프레임 지정
프롬프트: 장면의 움직임과 변화를 안내
첫 프레임은 항상 제공한 이미지에서 시작

예:

일출 호수 사진과 "아침 안개가 드리워지고 잔잔한 물결이 수면에 퍼진다" 프롬프트를 입력하면, 첫 프레임은 이미지 그대로, 이후 프레임은 물결과 안개가 움직입니다.

이미지-투-비디오를 써야 하는 경우

제품/브랜드 사진 등 특정 이미지를 기반으로 움직임을 만들고 싶을 때
시작 프레임의 시각적 일관성이 중요한 경우

텍스트-투-비디오가 적합한 경우

이미지 없이 아이디어만 빠르게 실험할 때
모델에게 장면 구성을 맡기고 싶을 때

전제 조건

API 호출 전 준비사항:

console.x.ai 계정
xAI 콘솔에서 발급받은 API 키 (환경 변수로 보관)
Python 3.8+ 또는 Node.js 18+ (예제 코드 제공)
공개 이미지 URL 또는 Base64 인코딩 데이터 URI

API 키 환경 변수 등록:

export XAI_API_KEY="your_key_here"

xAI Python SDK 설치:

클라이언트 사용 시

pip install xai-sdk

순수 HTTP 호출은 requests(Python) 또는 fetch(Node.js)만 있으면 충분합니다.

첫 번째 이미지-투-비디오 요청하기

curl 사용

curl -X POST https://api.x.ai/v1/videos/generations \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

응답 예시:

{
  "request_id": "d97415a1-5796-b7ec-379f-4e6819e08fdf"
}

비디오는 아직 준비되지 않았으므로 폴링이 필요합니다.

Python 사용 (순수 요청)

import os
import requests

api_key = os.environ["XAI_API_KEY"]

payload = {
    "model": "grok-imagine-video",
    "prompt": "Gentle waves move across the surface, morning mist rises slowly",
    "image": {
        "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/1/1a/24701-nature-natural-beauty.jpg/1280px-24701-nature-natural-beauty.jpg"
    },
    "duration": 6,
    "resolution": "720p",
    "aspect_ratio": "16:9"
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.x.ai/v1/videos/generations",
    json=payload,
    headers=headers
)

data = response.json()
request_id = data["request_id"]
print(f"Job started: {request_id}")

Base64 이미지 사용

공개 URL이 없을 때는 데이터 URI로 이미지 인코딩:

import base64

with open("my_image.jpg", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")

payload["image"] = {
    "url": f"data:image/jpeg;base64,{encoded}"
}

결과 폴링하기

비디오 생성은 비동기식이므로, 다음과 같이 결과를 폴링합니다.

GET https://api.x.ai/v1/videos/{request_id}

상태 값:

상태	의미
`"processing"`	비디오 렌더링 중
`"done"`	비디오 준비 완료, URL 제공
`"failed"`	생성 중 에러 발생

완료 응답 예시:

{
  "status": "done",
  "video": {
    "url": "https://vidgen.x.ai/....mp4",
    "duration": 6
  },
  "progress": 100
}

전체 Python 폴링 루프

import time

def poll_video(request_id: str, api_key: str, interval: int = 5) -> dict:
    url = f"https://api.x.ai/v1/videos/{request_id}"
    headers = {"Authorization": f"Bearer {api_key}"}

    while True:
        response = requests.get(url, headers=headers)
        data = response.json()
        status = data.get("status")

        print(f"Status: {status} | Progress: {data.get('progress', 0)}%")

        if status == "done":
            return data["video"]
        elif status == "failed":
            raise RuntimeError(f"Video generation failed for {request_id}")

        time.sleep(interval)

# 사용 예시
video = poll_video(request_id, api_key)
print(f"Video URL: {video['url']}")
print(f"Duration: {video['duration']}s")

TIP: 폴링 간격은 5초 이상으로 설정하세요. API는 분당 60회(초당 1회) 제한이 있습니다.

xAI Python SDK 사용

xai-sdk 라이브러리를 사용하면 폴링/상태처리/에러 전파를 자동으로 관리합니다.

from xai_sdk import Client
import os

client = Client(api_key=os.environ["XAI_API_KEY"])

video = client.video.generate(
    model="grok-imagine-video",
    prompt="Gentle waves move across the surface, morning mist rises slowly",
    image={"url": "https://example.com/landscape.jpg"},
    duration=6,
    resolution="720p",
    aspect_ratio="16:9"
)

print(f"Video URL: {video.url}")
print(f"Duration: {video.duration}s")

폴링, 재시도, 로깅 등 세밀한 제어가 필요하면 순수 HTTP 방식을, 간결한 코드가 필요하면 SDK를 사용하세요.

해상도, 재생 시간 및 화면 비율 제어

재생 시간

duration: 1~15초 (기본 6초)
예시:

  "duration": 10

해상도

값	설명
"480p"	기본값. 저비용, 빠른 생성
"720p"	고화질. 초당 0.07달러

"resolution": "720p"

화면 비율

값	사용 사례
"16:9"	기본, 풍경
"9:16"	모바일, 스토리
"1:1"	소셜 썸네일
"4:3"	프리젠테이션
"3:4"	인물
"3:2"	표준 사진
"2:3"	세로 인물

image가 주어지면 이미지 비율이 기본, 명시적으로 재정의 가능.

스타일 지정을 위한 참조 이미지 사용

image: 비디오 첫 프레임으로 사용됨
reference_images: 최대 7개, 스타일/분위기/조명 등 렌더링에 간접 영향

{
  "model": "grok-imagine-video",
  "prompt": "A product rotating slowly on a clean white surface",
  "image": {
    "url": "https://example.com/product-shot.jpg"
  },
  "reference_images": [
    {"url": "https://example.com/brand-style-reference-1.jpg"},
    {"url": "https://example.com/lighting-reference.jpg"}
  ],
  "duration": 6,
  "resolution": "720p"
}

참조 이미지는 첫 프레임 자체가 되지 않고, 스타일만 유도합니다.

image 없이 reference_images만 넘기면 텍스트-투-비디오 + 스타일 안내 효과.

비디오 확장 및 편집

비디오 확장

기존 비디오에 이어서 추가 생성:

curl -X POST https://api.x.ai/v1/videos/extensions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "The mist continues to lift as sunlight breaks through",
    "duration": 5
  }'

응답의 request_id로 동일하게 폴링.

비디오 편집

프롬프트 기반 비디오 내용 수정:

curl -X POST https://api.x.ai/v1/videos/edits \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "video_id": "your_original_request_id",
    "prompt": "Change the sky to a dramatic sunset with deep orange tones"
  }'

확장/편집 모두 비동기 방식 및 폴링 패턴 동일.

가격 분석: 10초 비디오 비용

구성 요소	비용
입력 이미지	$0.002/이미지
480p 출력	$0.05/초
720p 출력	$0.07/초

예시: 720p 10초 비디오

입력 이미지: $0.002
출력: 10초 × $0.07 = $0.70
총계: $0.702

예시: 480p 6초 비디오(기본)

입력 이미지: $0.002
출력: 6초 × $0.05 = $0.30
총계: $0.302

입력 이미지 요금은 매 요청마다 부과됩니다. 동일 이미지를 반복 사용한다면 호출을 효율적으로 계획하세요.

텍스트-투-비디오(이미지 미포함)의 경우 $0.002 입력 요금이 면제됩니다.

Apidog로 그록 비디오 API 통합을 테스트하는 방법

비동기 패턴은 단순 요청 테스트로는 검증이 어렵습니다. 다음을 자동화해야 합니다:

생성 요청이 request_id 반환
폴링 중 "processing" 상태 처리
최종 응답에서 status == "done" 및 비디오 URL 검증

Apidog의 Test Scenario 예시

1. 새 테스트 시나리오 생성

Apidog에서 테스트 모듈 → + → "Grok 이미지-투-비디오 비동기 흐름" 생성

2. 생성 요청 단계 추가

URL: https://api.x.ai/v1/videos/generations
메서드: POST
헤더: Authorization: Bearer {{xai_api_key}}
본문(JSON):

{
  "model": "grok-imagine-video",
  "prompt": "Gentle mist rises from the water as light filters through the trees",
  "image": {
    "url": "https://example.com/your-test-image.jpg"
  },
  "duration": 6,
  "resolution": "480p"
}

3. request_id 추출

변수 이름: video_request_id
소스: 응답 본문
추출: JSONPath, $.request_id

4. 폴링 루프

For 루프 프로세서 추가
루프 내부 GET 요청:
- URL: https://api.x.ai/v1/videos/{{video_request_id}}
- 헤더: Authorization: Bearer {{xai_api_key}}
변수 추출: video_status, JSONPath $.status
Wait 프로세서(5000ms) 추가
Break 조건: {{video_status}} == "done"

5. 비디오 URL 검증

For 루프 후, 마지막 GET
Assertion: $.video.url 필드가 비어있지 않음

자세한 활용법은 Apidog의 공식 가이드 참고

(모든 apidog.com 링크는 자동으로 UTM 파라미터가 추가됨)

시나리오 실행

테스트 시나리오에서 Run 클릭
보고서에는 각 단계 상태와 타이밍 표시

CI/CD 통합 예시

apidog run --scenario grok-video-async-flow --env production

일반적인 오류 및 해결 방법

401 Unauthorized

API 키 확인. 올바른 Bearer 토큰인지, xAI 콘솔에서 활성화되었는지 점검

422 Unprocessable Entity

필수 필드 누락, 잘못된 본문 구조, 접근 불가 이미지 URL 등. URL을 브라우저에서 직접 검증

이미지 URL 접근 불가

xAI 서버에서 접근 가능한 공개 URL 또는 Base64 데이터 URI 사용

"processing" 상태 무한 대기

일반적으로 30초~수분 소요. 10분 이상이면 새 요청 제출

429 요청 제한

분당 60회/초당 1회 제한. 폴링 간격 늘리기(time.sleep(1) 등)

Base64 업로드 오류

MIME 타입 접두사(data:image/jpeg;base64, 등) 정확히 입력

화면 비율 불일치

명시적 aspect_ratio가 원본 이미지와 크게 다르면 레터박스/크롭 발생

가능하면 원본 이미지 비율 유지

결론

그록 이미지-투-비디오 API는 정적 이미지를 애니메이션화하는 강력한 도구입니다. 이미지를 POST, 프롬프트 입력, request_id로 폴링, 결과 MP4 다운로드까지 간단한 패턴으로 사용할 수 있습니다.

grok-imagine-video 모델은 2026년 Artificial Analysis 1위를 차지했고, 한 달간 10억 개 이상의 비디오가 생성되었습니다.

비동기 폴링 패턴은 통합의 핵심 난관입니다. Apidog의 테스트 시나리오를 활용하면 변수 추출, 폴링 루프, 최종 URL 검증까지 자동화하여, 문제를 사전에 발견할 수 있습니다.

Apidog를 무료로 다운로드하여 통합을 시작해보세요. 신용카드 정보는 필요하지 않습니다.

자주 묻는 질문 (FAQ)

Q. 어떤 모델 이름을 써야 하나요?

A. grok-imagine-video를 model 필드에 지정하세요.

Q. image와 reference_images 차이는?

A. image는 첫 프레임, reference_images는 스타일 안내. 둘 다 조합 가능

Q. 비디오 생성 시간은?

A. 6초 480p: 1~3분, 15초 720p: 4~8분. 5초마다 폴링 권장

Q. 로컬 파일도 원본 이미지로 사용 가능?

A. 예. Base64 데이터 URI로 인코딩 후 image.url에 입력

Q. aspect_ratio를 생략하면?

A. image 입력 시 원본 이미지 비율, 아니면 기본 16:9

Q. 10초 720p 비디오 비용은?

A. 입력 이미지 $0.002 + 10초 × $0.07 = $0.702

Q. 요청 제한은?

A. 분당 60회, 초당 1회. 생성 POST/폴링 GET 모두 포함

Q. 15초 이상 비디오도 가능한가?

A. 예. /v1/videos/extensions로 이어붙이기 가능. 각 단계별로 폴링

2026년 Bird SMS API 가격: 비용 완벽 분석

Rihpig — Fri, 03 Apr 2026 07:08:34 +0000

TL;DR

Bird SMS API는 미국 발신 메시지당 $0.00331, 미국 수신 메시지당 $0.003부터 시작합니다. 주요 SMS API 제공업체 대비 상당히 저렴하며, 하루 5건 무료 SMS가 포함된 무료 요금제도 지원합니다. 월 $49 Pro 요금제에는 1,000건의 SMS 크레딧이 포함됩니다.

오늘 Apidog를 무료로 사용해보세요

소개

MessageBird는 2023년에 Bird로 브랜드를 변경했습니다. AI 기반 옴니채널 커뮤니케이션(SMS, WhatsApp, 이메일, 음성)에 집중하고, 가격 모델 또한 투명한 종량제 요금으로 변경되었습니다. Bird의 기본 SMS 비용은 Twilio, Vonage, 그 외 주요 공급업체보다 낮습니다.

💡 SMS 통합 개발 시, 정확한 가격 데이터와 빠른 API 테스트가 모두 필요하다면 Apidog를 활용하세요. 추가 코드 없이 Bird API 요청을 설계·테스트하고 응답을 검증할 수 있습니다. apidog.com에서 무료로 시작하면, 몇 분 만에 Bird SMS 통합을 검증할 수 있습니다.

이 글에서는 2025~2026년 기준 Bird SMS 실제 비용, 추가 비용 요인, 그리고 경쟁사와의 비교까지 실무적인 관점에서 다룹니다.

Bird SMS 가격 개요

Bird의 SMS 가격 구조는 두 가지로 나뉩니다.

플랫폼 요금제 (월별 구독)
메시지당 요금 (요금제 외 종량제)

요금제	월 비용	포함된 SMS
무료	$0	일 5건의 SMS
Pro	$49	월 1,000건의 SMS
Enterprise	맞춤형	맞춤형 볼륨

요금제 초과분은 별도 과금됩니다. 미국 기준 메시지당 요금은 아래와 같습니다.

발신 SMS: $0.00331/건
수신 SMS: $0.003/건

Bird의 상세 요금 페이지에서 항상 최신 요금을 확인하세요: bird.com/en/pricing/sms

가격 분석: SMS, MMS, WhatsApp, 이메일

SMS

미국 SMS는 $0.00331/건(발신). 지역별 예시:

국가	발신 요금(예시)
미국	~$0.00331
영국	~€0.036
호주	~€0.009
독일	~€0.056
인도	경로에 따라 다름
브라질	~€0.047

미국/캐나다는 별도의 이동통신사 요금(10DLC 등)이 추가됩니다.

MMS

MMS(사진 포함)는 SMS보다 3~5배 높은 비용이 발생합니다. 미국/캐나다 번호만 지원하며, 국가별 MMS 요금은 bird.com/en/pricing/sms에서 확인하세요.

Bird 처리 수수료 (1,000 메시지당):

볼륨	1,000 메시지당
1 ~ 1,000	$0.001
1,001 ~ 100,000	$0.005
100,001 ~ 500,000	$0.0045
500,001 이상	$0.004

Meta 통과 수수료 (미국 기준):
- 마케팅: $0.0250/대화
- 유틸리티: $0.0034/대화
- 인증: $0.0034/대화

Meta 수수료는 마크업 없이 원가 통과됩니다.

이메일

API 등급 기준, 이메일은 $0.001/건부터 시작. Pro 요금제에는 월 10,000건 이메일이 포함됩니다.

음성

음성 API는 분당 $0.013~$0.015(미국 발신 기준). 수신은 더 저렴하며, 대량 요금은 별도 협의가 필요합니다.

Bird 청구서에 영향을 미치는 요인

국가 및 이동통신사 라우팅

국가별 요금 차이가 큽니다(예: 미국 <$0.004, 독일 >€0.05). 발송 국가별 요금표를 반드시 확인하세요.
번호 유형
- 10DLC: 표준 미국 번호, TCR 등록 필요
- 단문 코드: 5~6자리, 월 $500~$1,000 임대료
- 수신자 부담 번호: 월 $2~$3 번호 임대료는 별도 청구됩니다.
메시지 길이/인코딩
- GSM-7: 160자/세그먼트, 초과 시 분할 과금
- 유니코드: 70자/세그먼트 예) 200자 메시지 + 이모지 → 3개 세그먼트 과금
채널 혼합

SMS 실패 시 WhatsApp 등으로 대체하면 각각 요금이 추가됩니다. Flow Builder 자동화 사용 시 반드시 비용을 시뮬레이션하세요.
볼륨

대량 발송자는 Enterprise 요금제에서 맞춤 할인 협상 가능.

숨겨진 비용 및 수수료

미국 이동통신사 수수료(10DLC)
- 브랜드 등록: $4~$44(1회)
- 캠페인 등록: 약 $10/월(캠페인당)
- 메시지당 추가 이동통신사 요금
전화번호 임대
- 장문 코드: 월 $1~$2
- 수신자 부담 번호: 월 $2~$3
- 단문 코드: 월 $500~$1,000
인바운드 SMS 및 웹훅 처리
- 미국 인바운드 SMS: $0.003/건
- 옵트아웃/헬프 등 키워드 응답도 과금
플랫폼 구독
- Pro 요금제: 월 $49(1,000건 SMS 포함)
- 볼륨 초과 시 추가 과금

Bird와 다른 대안 비교

제공업체	미국 발신 SMS	미국 수신 SMS	참고
Bird	$0.00331	$0.003	가장 낮은 기본 요금
Twilio	$0.0079	$0.0079	높은 기본 요금, 생태계 강점
Telnyx	~$0.004	~$0.001	경쟁력, 이동통신사 직접 모델
Plivo	$0.0055	$0.0005	더 낮은 수신 요금

Bird는 발신 비용에서 가장 저렴하며, 옴니채널/자동화가 필요한 경우 최적입니다. 단순 SMS API만 원하면 Telnyx나 Plivo도 고려하세요.

Bird 시작하기

bird.com에서 무료 계정 생성 (하루 5건 무료 SMS, 신용카드 불필요)
브랜드/캠페인 등록 (10DLC 규정 준수, 대시보드에서 신청, 1~3영업일 소요)
전화번호 프로비저닝 (Numbers API 또는 대시보드 사용)
첫 API 호출 Bird는 REST API(JSON) 기반입니다.

   curl -X POST https://api.bird.com/v1/messages \
     -H "Authorization: AccessKey {YOUR_ACCESS_KEY}" \
     -H "Content-Type: application/json" \
     -d '{
         "originator": "+1XXXXXXX",
         "recipients": ["+1YYYYYYY"],
         "body": "Test message from Bird API."
      }'

인증/SDK/웹훅 등 Bird 공식 문서: docs.bird.com

결론

Bird SMS API는 미국 발신 메시지당 $0.00331로 업계 최저가를 제공합니다. 무료 요금제에서 신용카드 없이 바로 테스트 가능하며, Pro 요금제(월 $49)는 월 1,000건 SMS로 팀 스타트에 적합합니다.

단, 미국 10DLC 이동통신사 수수료, 번호 임대료, 국가별 국제 요금 등 숨겨진 비용까지 명확히 산정해야 합니다. 초기에 비용 모델링에 포함시키세요.

실제 통합 전 Apidog에서 Bird API 요청 빌딩, 테스트 시나리오, 응답 검증을 자동화하면 개발 효율이 높아집니다.

FAQ

미국에서 Bird SMS API 메시지당 가격은 얼마인가요?

Bird는 미국 발신 SMS당 $0.00331, 수신 SMS당 $0.003을 청구합니다. 개발자 API 등급 기준이며, 10DLC 등 이동통신사 수수료는 별도입니다.

Bird는 MessageBird와 같은 회사인가요?

네. MessageBird는 2023년에 Bird로 리브랜딩되었습니다. 2011년 네덜란드 설립, 글로벌 고객(Heineken, Uber 등)이 사용 중입니다. 문서상 일부 MessageBird 명칭이 남아있을 수 있습니다.

Bird는 수신 SMS에도 비용이 부과되나요?

네. 미국 수신 메시지당 $0.003이 발생합니다. 옵트아웃/도움말 응답 등도 포함됩니다.

Bird 무료 요금제는 어떤가요?

하루 5건 SMS, 10건 이메일, 15건 AI 에이전트 메시지 포함. 신용카드 없이 API 테스트에 적합합니다.

Bird SMS 가격은 Twilio와 비교해 어떤가요?

Bird의 미국 발신 SMS($0.00331)는 Twilio($0.0079)보다 저렴합니다. 월 10만 건 기준 Bird는 $331, Twilio는 $790(대량 발송시 Twilio 할인 가능).

Bird SMS에 숨겨진 수수료가 있나요?

통신사 등록, 캠페인 등록(약 $10/월), 메시지당 통신사 요금, 번호 임대료(월 $1~$2), 국제 메시지 고요금 등이 추가될 수 있습니다.

실제 메시지 없이 Bird SMS API를 테스트하려면?

Apidog의 Smart Mock 기능을 활용하면 API 응답을 시뮬레이션할 수 있습니다. 또한 Bird 샌드박스를 통해 본인 인증 번호로 테스트가 가능합니다. Apidog 테스트 시나리오로 실서비스에 영향 없이 검증하세요.

트윌리오 SMS API 가격: 2026년 완벽 분석

Rihpig — Fri, 03 Apr 2026 03:54:36 +0000

요약

미국 장거리 코드 SMS (발신 및 수신): 메시지당 $0.0083
MMS 발신: 메시지당 $0.022; MMS 수신: 메시지당 $0.0165
수신자 부담 SMS: 메시지당 $0.0083 + 통신사 추가 요금
단축 코드 임대료: 무작위 코드 월 $1,000; 맞춤 코드 월 $1,500
10DLC 브랜드 등록: $4.50 일회성 요금 (2025년 8월 업데이트); 캠페인 월 $1.50 ~ $10
전화번호 (장거리 코드): 월 $1.15; 수신자 부담: 월 $2.15
통신사 요금은 모든 기본 가격에 추가됨
월 15만 메시지 이상 시 자동 볼륨 할인
무료 체험 가능; 시작 시 신용카드 불필요

지금 Apidog를 체험해보세요

서론

Twilio는 많은 개발팀에게 기본적인 SMS API로 자리잡았습니다. 문서가 잘 되어 있고, 가동 시간도 안정적이며, REST API도 깔끔하게 설계되어 있습니다. 하지만 사이드 프로젝트에서 실제 프로덕션 환경으로 넘어가면, 비용이 빠르게 증가합니다. 단순히 메시지당 요금만 내는 것이 아니라, Twilio 기본 요금, 통신사 수수료, 전화번호 요금, 10DLC 등록 비용까지 추가로 지불해야 합니다.

💡 Tip: SMS 워크플로우를 프로덕션에 적용하기 전, Apidog를 사용해 Twilio 웹훅 응답이 OpenAPI 스펙에 맞는지 자동화 테스트로 검증하세요. 상태 코드, 응답 스키마, CI/CD 계약 테스트까지 Apidog 무료 체험으로 확인할 수 있습니다.

이 글에서는 Twilio 가격 구조의 모든 요소를 분석합니다. 청구서를 키우는 요인, 놓치기 쉬운 부분, 그리고 Twilio가 다른 대안과 어떻게 비교되는지까지 실용적인 정보를 제공합니다.

Twilio SMS 가격 개요

Twilio는 종량제(Pay-as-you-go) 가격 정책을 사용합니다. 메시지 세그먼트별, 전화번호별, 그리고 선택적 기능 및 등록 비용이 별도 청구됩니다. 약정 사용 할인을 별도로 협상하지 않는 한, 계약이나 최소 지출 의무는 없습니다.

미국 장거리 코드 SMS 기본 요금: 인바운드/아웃바운드 모두 세그먼트당 $0.0083
통신사 수수료, 번호 임대료, 10DLC 등록 비용이 추가됨
월 15만 메시지 이상 시 자동 볼륨 할인(별도 협상 불필요)

가격 분석: SMS, MMS, 수신자 부담, 단축 코드

장거리 코드 SMS (10자리 번호)

장거리 코드는 미국에서 대부분의 A2P(애플리케이션-대-개인) 메시징에 사용됩니다.

메시지 유형	세그먼트당 가격
SMS 발신	$0.0083
SMS 수신	$0.0083
MMS 발신	$0.022
MMS 수신	$0.0165

중요: Twilio는 메시지당이 아닌 세그먼트당 요금을 청구합니다. GSM-7 기준 160자, 유니코드 포함 시 70자마다 1세그먼트로 계산됩니다. 예를 들어, 200자 일반 텍스트는 2세그먼트 비용이 발생합니다.

수신자 부담 번호

SMS 인/아웃바운드: 세그먼트당 $0.0083
MMS 발신: $0.022 / MMS 수신: $0.02

수신자 부담 번호는 대량 일방향 메시징에 적합하며 10DLC 등록이 필요 없어서 비용 절감 가능. 단, 최대 처리량을 위해 별도 인증 필요.

단축 코드 (5-6자리 번호)

단축 코드는 대량/고속 캠페인에 사용됩니다. SMS 요금은 동일하지만 번호 임대료가 매우 높음.

단축 코드 유형	월별 비용
무작위 단축 코드	월 $1,000 (분기 청구)
맞춤 단축 코드	월 $1,500 (분기 청구)
자체 맞춤 단축 코드	월 $500 (분기 청구)

MMS 활성화 시 $500 일회성 요금 추가

볼륨 할인

Twilio는 장거리 코드, 수신자 부담, 단축 코드 모두 자동 계층 볼륨 할인을 적용합니다.

월별 메시지	세그먼트당 가격
1 ~ 150,000	$0.0083
150,001 ~ 300,000	$0.0081
300,001 ~ 500,000	$0.0079
500,001 ~ 750,000	$0.0077
750,001 ~ 1,000,000	$0.0075
1,000,001+	$0.0073

볼륨은 번호 유형별로 분리되어 계산됩니다.

Twilio 청구서에 영향을 미치는 요인

전화번호 유형

발신 번호 유형에 따라 요금이 달라집니다. 장거리 코드, 수신자 부담, 단축 코드 각각 별도 볼륨 계층을 가짐.

메시지 세그먼트

모든 메시지는 세그먼트 단위로 청구됩니다. 유니코드 문자, 긴 메시지는 세그먼트 수가 늘어나 총 비용이 증가합니다.

통신사 수수료

Twilio 기본 요금 외에, 미국 주요 통신사는 메시지당 자체 추가 수수료를 부과하며, Twilio는 이 비용을 그대로 전달합니다.

장거리 코드 통신사 수수료 (SMS 발신):

통신사	발신 수수료
AT&T	$0.0035
T-Mobile	$0.0045
Verizon	$0.004
US Cellular	$0.005
기타 모든 통신사	$0.004

MMS는 AT&T $0.009, T-Mobile $0.01 추가.

예시: AT&T로 SMS 1건 발신 시, $0.0083(Twilio) + $0.0035(통신사) = $0.0118/세그먼트 → 기본 가격보다 42% 높음.

대상 국가

국제 메시지 요금은 국가별로 상이. 예: 영국 $0.04, 인도 $0.0029, 브라질 $0.075 등.

10DLC 등록

미국 A2P 10DLC 시스템은 기업이 브랜드 및 메시징 캠페인을 등록해야 하며, 미등록 트래픽은 필터링됩니다.

숨겨진 비용 및 수수료

10DLC 등록 수수료

2025년 8월 TCR 정책 업데이트로 가격이 변경됨.

브랜드 등록: 개인/소량 $4.50, 표준 $46 (일회성)
캠페인 등록: 심사 $15(일회성), 캠페인별 월 $1.50~$10

캠페인 유형	월별 요금
개인 사업자	$2
소량 혼합	$1.50
표준	$10
자선단체/501(c)(3)	$3
긴급 서비스	$5

표준 심사 $41.50, 이의제기 $11, Authentication Plus 재시도 $12.50/회

전화번호 수수료

전화번호 유지 월별 요금: 장거리 코드 $1.15, 수신자 부담 $2.15

여러 번호 프로비저닝 시 누적 비용 주의

실패 메시지 처리 수수료

"실패" 상태 메시지당 $0.001 청구

선택적 기능 추가 요금

Engagement Suite(링크 단축, 클릭 추적): 월 1,000건 무료, 이후 건당 $0.015
Compliance Toolkit(AI 규정 준수): 건당 $0.015

지원 플랜

무료 지원은 제한적. 유료 Developer 플랜 월 $250~, 엔터프라이즈는 그 이상

Twilio가 대안들과 비교되는 방식

공급자	미국 SMS 발신	미국 SMS 수신	전화번호	10DLC 필요 여부
Twilio	$0.0083 + 통신사 수수료	$0.0083 + 통신사 수수료	월 $1.15	예
Plivo	$0.005	$0.00035	월 $0.80	예
Telnyx	$0.004	$0.004	월 $1.00	예
Bird	약 $0.007	약 $0.007	상이함	예

Plivo, Telnyx는 Twilio보다 발신/수신 요금이 저렴
Twilio는 개발자 경험, 문서, 글로벌 커버리지, 생태계 통합에서 강점
볼륨이 중요하다면 Plivo/Telnyx, 복잡한 기능/서드파티 연동이 필요하다면 Twilio 고려

Twilio를 무료로 테스트하는 방법

신용카드 없이 무료 체험 계정 생성 가능
체험 계정에 소량 크레딧 제공
인증되지 않은 번호로 메시지 전송 시 "Sent from your Twilio trial account" 접두사 포함(유료 업그레이드시 제거)
무료 체험으로 할 수 있는 것:
- 테스트 번호 프로비저닝
- API를 통한 SMS 송수신
- 수신 웹훅 전달 테스트
- 콘솔 및 사용 로그 탐색
업그레이드 후에는 종량제, 월 최소 요금 없음

Apidog로 Twilio SMS 통합을 테스트하는 방법

Twilio 자격 증명과 웹훅을 설정했다면, 자동화된 테스트로 통합 안정성을 검증해야 합니다. 수동 메시지 전송은 확장성과 신뢰성이 떨어집니다.

Apidog 테스트 시나리오 활용법:

Twilio 웹훅 엔드포인트 OpenAPI 스펙을 테스트 시나리오로 가져오기
SMS 발송, 전송 콜백 수신, 인바운드 회신 등 단계별 플로우 추가
오케스트레이션 모드로 단계 순서 지정 및 연속 실행
{{$.stepId.response.body.field}} 구문으로 단계별 데이터(예: 메시지 SID) 연결

예시 코드 스니펫:

{
  "to": "+1XXXXXXXXXX",
  "from": "+1YYYYYYYYYY",
  "body": "테스트 메시지"
}

이후, 전송 결과에서 SID를 받아 다음 단계에서 활용.

계약 테스트까지 적용하려면:

OpenAPI 스펙에 웹훅 페이로드 스키마 정의
Apidog에서 응답 유효성 자동 검사(상태 코드, 필수 필드, 데이터 타입, 추가 필드 없음 등)
테스트/디버그/자동화 단계 모두에서 스키마 일치 여부 자동 검증

시작 방법:

Apidog 무료 다운로드
Twilio API 스펙 가져오기 또는 웹훅 스키마 정의
실제 SMS 워크플로우를 반영한 테스트 시나리오 생성 및 실행

결론

Twilio SMS API 가격은 미국 장거리 코드 기준 세그먼트당 $0.0083에서 시작하지만, 실제 메시지 비용에는 통신사 수수료, 번호 임대료, 10DLC 등록 등이 반드시 포함됩니다. 예를 들어 AT&T 발신은 세그먼트당 약 $0.0118이 됩니다. 표준 10DLC 캠페인 사용 시 월 $10이 추가됩니다.

가격 구조는 투명하며 할인은 자동 적용
볼륨, 메시지 세그먼트, 통신사 수수료, 번호, 등록 비용 등 모든 요소를 합산해 모델링 필요
통합을 구축했다면 Apidog의 테스트 시나리오와 계약 테스트로 Twilio 웹훅 흐름 및 API 응답 일치 여부를 자동화 검증할 수 있음

자주 묻는 질문

Q: Twilio에서 미국 발신 SMS의 기본 가격은 얼마인가요?

A: 장거리 코드 발신 SMS는 세그먼트당 $0.0083(기본) + 통신사 수수료(AT&T $0.0035 등)로, AT&T 발신 실제 비용은 $0.0118/세그먼트입니다.

Q: Twilio는 수신 SMS에 대해 요금을 부과하나요?

A: 예. 장거리 코드/수신자 부담 번호 모두 수신 SMS 세그먼트당 $0.0083 청구. 발신 통신사에 따라 추가 수수료 발생 가능.

Q: 10DLC는 무엇이며, 비용이 있나요?

A: 10DLC는 미국 10자리 장거리 코드 A2P 메시징 등록 시스템입니다. 브랜드 등록 $4.50(일회성), 캠페인당 월 $1.50~$10 필요.

Q: Twilio 단축 코드 비용은?

A: 무작위 단축 코드 월 $1,000, 맞춤 단축 코드 월 $1,500(분기 청구). MMS 활성화시 $500 일회성 추가. SMS 요율은 $0.0083/건.

Q: 볼륨 할인이 있나요?

A: 예, 번호 유형별 월 15만건 초과 시 자동 할인이 적용되며, 100만건 이상은 $0.0073까지 내려감.

Q: Twilio 무료 체험이 있나요?

A: 예. 신용카드 없이 무료 체험계정 생성, 크레딧 제공, 업그레이드 전에는 발신 메시지에 접두사 포함.

Q: 저렴한 Twilio 대안은?

A: Plivo(발신 $0.005, 수신 $0.00035), Telnyx(발신/수신 $0.004)가 있음. 기능 및 문서 품질은 Twilio가 우위.

실제 요금 모델링, 자동화된 테스트, 비용 최적화까지, Twilio SMS API를 제대로 활용하려면 위 내용을 실전으로 적용해보세요.

Vonage SMS API 가격: 2026년 요금 안내

Rihpig — Fri, 03 Apr 2026 03:49:19 +0000

요약 (TL;DR)

미국에서 Vonage SMS API 요금은 발신 메시지당 $0.00809, 수신 메시지당 $0.00649부터 시작합니다. 월 최소 요금이 없으므로, 보내고 받는 만큼만 지불합니다. 국제 요금은 국가별로 다르며 일부 시장에서는 메시지당 $1.00를 초과할 수 있습니다. Vonage SMS 통합 기능을 구축하거나 테스트하는 경우, Apidog를 사용하면 코드를 출시하기 전에 테스트 요청을 쉽게 보내고, 응답을 검증하며, 오류를 포착할 수 있습니다.

오늘 Apidog를 무료로 체험해 보세요

소개

Nexmo에 대해 들어본 적이 있다면 이미 Vonage를 아실 겁니다. 2016년, Vonage는 개발자 중심의 SMS 및 통신 API 플랫폼인 Nexmo를 인수했습니다. Nexmo 브랜드는 개발자들 사이에서 수년 동안 유지되었으며, developer.vonage.com (이전 nexmo.com/developers)이 기술 허브 역할을 하는 것을 여전히 볼 수 있습니다. 2022년, Ericsson은 Vonage 인수를 완료하여 글로벌 통신 강자로 편입시켰지만, API 사업을 위해 Vonage 브랜드를 그대로 유지했습니다.

오늘날 Vonage는 10만 개 이상의 기업에 서비스를 제공하며, 160만 명의 등록된 개발자가 API를 기반으로 구축하고 있습니다. 이는 사용한 만큼만 지불하는(pay-as-you-go) 요금 모델, 약정 없는 계약, 190개 이상의 국가를 포괄하는 성숙한 플랫폼입니다.

💡 팁: 통합 작업을 더 진행하기 전에, 강력한 API 테스트 도구가 필요하다면 Apidog를 활용하세요. Vonage SMS 요청 테스트, 응답 스키마 검증, 여러 API 호출 워크플로 자동화까지 모두 무료로 시작할 수 있습니다(신용카드 불필요).

Vonage SMS 요금 개요

Vonage는 SMS API에 대해 종량제 모델을 제공합니다. 시작 시 플랫폼 수수료나 월 구독료가 없으며, 메시지당 요금을 지불합니다. 요금은 국가, 번호 유형에 따라 달라집니다.

미국 주요 요금은 다음과 같습니다:

메시지 유형	메시지당 가격
발신 SMS (미국 LVN)	$0.00809
수신 SMS (미국 LVN)	$0.00649
발신 SMS (미국 수신자 부담)	영업팀에 문의
수신 SMS (미국 수신자 부담)	무료

LVN(Local Virtual Number): Vonage의 표준 10DLC(10자리 장문 코드) 번호를 의미합니다.
국가별, 번호 유형별 요율은 Vonage 대시보드에서 실시간으로 확인 및 Excel 요금표 다운로드 가능.

요금 세부 정보: 발신, 수신, MMS, WhatsApp

발신 SMS

발신 메시지는 앱에서 최종 사용자에게 전송됩니다.
미국 LVN 사용 시 $0.00809/메시지(2026년 초 기준).
공식 대시보드에서 최신 요율을 반드시 확인.

수신 SMS

Vonage 번호로 수신되는 메시지는 $0.00649/메시지(미국 LVN).
일부 수신자 부담 번호는 무료 수신 가능(계정별 확인 필요).

MMS 요금

MMS는 Vonage Messages API로 지원되나, 요금은 공개되지 않음.
시장/통신사별로 달라지므로 영업팀에 문의 필요.

Vonage를 통한 WhatsApp

Meta(WhatsApp) 요금과 별도의 Vonage 플랫폼 수수료가 존재:
1. WhatsApp 수수료: Meta 기준, 대화 카테고리별 상이(마케팅/인증 등). Meta WhatsApp 요금 참고.
2. Vonage 플랫폼 수수료: 메시지당 $0.00015부터, 카테고리/볼륨에 따라 변동.

Facebook Messenger

Messages API 이용 시 $0.0011/메시지.

RCS (Rich Communication Service)

미국 내 이동통신사별 요율:

이동통신사	RCS 리치(텍스트)	RCS 리치 미디어
T-Mobile	$0.00620	$0.01250
Verizon	$0.00400	$0.00600
AT&T	$0.00450	$0.01000
US Cellular	$0.00620	$0.01350

RCS 국가당 $600 일회성 설정 수수료 추가.

Vonage 청구서에 영향을 미치는 요인

월별 비용을 결정하는 주요 변수:

목적지 국가

국가별 요금 차이 큼(미국 < $0.01, 일부 아프리카/동남아 $0.50+).
글로벌 요금표 확인 필수.

번호 유형

장문 코드(10DLC): 표준, 저렴.
수신자 부담 번호: A2P 캠페인용, 수신 무료 빈번.
단문 코드: 대량 발송용, 등록 필요, 대여료 높음.

번호 대여료

미국 LVN은 월 몇 달러부터 시작.
수신자 부담/단문 코드는 더 비싸며, 메시지당 요금 외 추가.

메시지 인코딩

표준 SMS: GSM-7(160자).
유니코드(이모티콘 등) 포함 시 70자/1SMS로 계산, 장문은 여러 SMS로 나뉨.

이동통신사 할증료

미국 통신사들은 10DLC 등에서 별도 할증료 부과, Vonage가 그대로 전달함.

주의해야 할 숨겨진 비용

지원 등급

무료: 커뮤니티/문서.
프리미엄(24/7, 전담 관리자): $3,300/월.

애드온 API

애드온	월별 비용
Audit API	$550/월
자동 교정(PII 제거)	$1,100/월
Reports API	$495/월(또는 CDR당 $0.00049)

Audit API: 규제 준수 용도.
자동 교정: 로그 내 PII 자동 제거.

Verify API 비용

성공 인증당 $0.0572 (실패/시도별 메시징 요금 별도).

번호 등록(미국 10DLC)

TCR 등록 필수(브랜드 일회성/캠페인 월별 수수료).
미등록 시 메시지 필터링 위험.

Vonage 대(對) 대안

미국 SMS 주요 제공업체 비교:

제공업체	미국 발신 SMS	미국 수신 SMS	무료 체험	지원
Vonage	$0.00809	$0.00649	예(인증 번호만)	유료 등급, 24/7 월 $3,300
Twilio	$0.0079	$0.0075	예($15 크레딧)	유료 $250/월~
Plivo	$0.0055	$0.0005	예	무료 기본, 유료 옵션
Telnyx	$0.004	$0.002	예($5 크레딧)	무료 이메일, 유료 전화

Telnyx: 저렴하지만 신생 플랫폼.
Plivo: 수신 요금 저렴, 개발자 평판 높음.
Twilio: 생태계/문서/통합 강점.
Vonage: 가격 중간, 통신사급 네트워크 제공.

Vonage 무료로 체험하는 방법

Vonage 무료 체험 계정을 빠르게 시작할 수 있습니다.

얻을 수 있는 것

테스트용 Vonage 가상 번호
즉시 발급되는 API Key, Secret
전체 문서/SDK 접근
제한된 테스트 크레딧

제한되는 사항

체험 계정은 인증된 전화번호로만 메시지 발신 가능(사기 방지).
유료 전환 전 임의 번호 발신 불가.

시작 방법 (Step-by-step)

dashboard.nexmo.com 또는 vonage.com/communications-apis 접속
이메일로 무료 계정 생성
전화번호 인증
대시보드에서 API Key/Secret 획득
REST API 또는 공식 SDK(Node.js, Python, PHP, Ruby, Java, .NET, Go) 활용해 첫 API 호출 실행

Apidog로 Vonage SMS 통합을 테스트하는 방법

API Key와 Secret이 준비되었다면, Apidog로 실제 메시지 전송 전 자동화 테스트를 구축할 수 있습니다.

테스트 시나리오 구성 절차

Apidog 테스트 모듈에서 새 시나리오 생성
단계 추가 방식:
- OpenAPI 스펙으로 Vonage 엔드포인트 가져오기
- REST API 엔드포인트 직접 요청 추가
- Vonage 문서의 cURL 명령 복사 후 자동 변환
예시: Vonage SMS 발송 요청(https://rest.nexmo.com/sms/json)에 API Key, Secret, 발신자, 수신자, 메시지 본문 입력

응답 검증

Apidog는 응답 스키마 자동 체크 지원. Vonage SMS API 성공 응답 구조는 다음과 유사:

{
  "messages": [
    {
      "status": "0",
      "message-id": "xxxxxxxxx"
      // 기타 필드
    }
  ]
}

테스트 어설션 예시:
- HTTP 상태 코드 200
- messages[0].status === "0"
- messages[0].message-id 값 존재
실패(예: status 1, 2, 4 등) 시 테스트가 빨간색으로 표시되며, 즉시 응답 본문 확인 가능.

요청 간 데이터 전달

Apidog의 {{$.stepId.response.body.field}} 문법으로 message-id 등 응답값을 다음 요청에 자동 전달 가능.

CI/CD 자동화

Apidog는 GitHub Actions, GitLab CI, Jenkins 연동 지원.
테스트 시나리오를 CLI로 내보내고 풀리퀘스트마다 실행, SMS 통합 회귀 방지에 최적.

Apidog.com에서 무료로 시작하세요. 신용카드 불필요.

결론

Vonage SMS API는 월별 최소 요금 없이 종량제로 운영됩니다. 미국 기준 발신 $0.00809, 수신 $0.00649/메시지. 비용은 국가, 번호, 인코딩에 따라 달라지며, Audit API, 자동 교정, 24/7 지원 등은 별도 월 비용이 추가됩니다.

대안으로 Telnyx, Plivo는 저렴하며, Twilio는 생태계가 넓습니다. Vonage는 Ericsson 지원의 글로벌 안정성이 필요할 때 적합합니다.

라이브 전환 전 Apidog로 Vonage 메시지 흐름 자동 테스트를 구축해, 모든 응답을 검증하고 개발 단계에서 오류를 사전에 방지하세요.

자주 묻는 질문 (FAQ)

Vonage는 Nexmo와 동일한가요?

네. Vonage는 2016년에 Nexmo를 인수했습니다. 개발자 플랫폼은 여전히 developer.vonage.com에서 접근할 수 있으며, 많은 레거시 통합은 rest.nexmo.com을 API 엔드포인트로 사용합니다. 이제 두 브랜드는 동일한 제품을 지칭합니다.

Vonage는 SMS에 대해 월별 요금을 부과하나요?

SMS API 자체에는 월별 플랫폼 요금이 없습니다. 보내고 받는 메시지당 요금과 사용하는 가상 번호에 대한 번호 대여료를 지불합니다. Audit API 및 자동 교정과 같은 선택적 애드온에는 월별 요금이 부과됩니다.

Vonage 전화번호는 얼마인가요?

미국 지역 가상 번호(장문 코드)는 월 몇 달러부터 시작합니다. 수신자 부담 번호와 단문 코드는 더 비쌉니다. 해당 국가의 현재 번호 대여 요금은 Vonage 대시보드에서 확인하세요.

Vonage SMS는 어떤 국가를 지원하나요?

Vonage는 190개 이상의 국가에서 SMS를 지원합니다. 요율은 크게 다릅니다. 이동통신사 관계가 제한적인 일부 국가는 메시지당 $0.50 이상이 들 수 있습니다. 전체 내역은 Vonage 대시보드에서 글로벌 요금표를 다운로드하세요.

Vonage는 대량 할인(볼륨 할인)을 제공하나요?

네. Vonage는 대량 발신자를 위한 맞춤형 요금을 제공합니다. 월별 메시지 양이 많은 경우, 영업팀에 문의하여 맞춤 요율을 협상하세요. 맞춤 계약이 있기 전까지는 기본 종량제 요율이 적용됩니다.

무료로 수신 SMS를 받을 수 있나요?

미국 수신자 부담 번호는 종종 무료로 수신 SMS를 받습니다. 장문 코드 번호는 미국에서 수신 메시지당 $0.00649를 부과합니다. 수신 요금은 국가별로 다르므로, 대상 시장의 요금표를 확인하세요.

Vonage는 SMS 부문에서 Twilio와 어떻게 비교되나요?

Vonage의 미국 발신 요율($0.00809)은 Twilio($0.0079)보다 약간 높습니다. Twilio는 더 큰 개발자 생태계와 더 많은 타사 통합을 가지고 있습니다. Vonage는 Ericsson을 통한 이동통신사 수준의 네트워크 관계에서 차별화되며, 특정 국제 시장에서 경쟁력 있는 가격을 제공하는 경향이 있습니다. 순수한 미국 A2P 메시징의 경우, 가격 차이가 충분히 작아서 개발자 경험과 지원 품질이 최종 결정을 이끄는 경우가 많습니다.

Cursor 3, API 개발자에게 어떤 의미일까요?

Rihpig — Fri, 03 Apr 2026 03:44:14 +0000

요약: Cursor 3는 2026년 4월 2일 출시된 IDE 혁신 버전으로, 에이전트 중심의 작업 공간과 병렬 실행, 구조화된 MCP 도구 출력, 클라우드-로컬 핸드오프 등 API 개발 생산성을 극대화하는 주요 기능을 제공합니다. 특히 Apidog의 MCP 서버와 연동하면, AI 에이전트가 라이브 API 사양을 직접 읽고 스키마 기반 코드를 자동 생성할 수 있습니다.

지금 Apidog을 사용해보세요

이미 예견되었던 변화

AI 코드 에디터는 지난 2년간 빠르게 발전해왔지만, Cursor 3는 단순한 업데이트가 아닙니다. 개발 환경의 핵심을 에디터 중심에서 에이전트 중심으로 완전히 재설계했습니다.

이전에는 파일을 열고, 에이전트에게 한 번씩 요청하고, 직접 변경사항을 검토해야 했습니다. 이제는 브라우저 탭처럼 여러 에이전트를 동시에 실행하고, 병렬로 작업하며, 가장 적합한 결과를 선택할 수 있습니다.

API 개발은 스펙 관리, 테스트, 문서화, 스키마 일치 등 여러 작업을 병렬로 수행해야 하므로 Cursor 3의 변화가 특히 실질적입니다.

💡Cursor 3는 API 사양을 직접 알지 못합니다. Apidog MCP 서버와 연결하면, 에이전트가 OpenAPI 스키마, 엔드포인트, 테스트 시나리오를 실시간으로 읽어와 정확한 스키마 기반 코드를 생성할 수 있습니다.

아래에서는 Cursor 3의 주요 업데이트, API 개발에 미치는 영향, 그리고 Apidog MCP 서버와 연결하여 바로 적용할 수 있는 워크플로우를 단계별로 안내합니다.

Cursor 3의 새로운 기능

Cursor 3의 주요 변화와 API 개발자를 위한 핵심 기능을 실전 관점에서 살펴봅니다.

에이전트 창

에이전트 창은 에디터 중심 레이아웃을 대체하며, 여러 리포지토리와 환경(로컬, Git 워크트리, 원격 머신, 클라우드)에서 에이전트를 병렬로 실행할 수 있습니다.

실행: Cmd+Shift+P -> Agents Window로 진입. 에디터와 에이전트 창 간 자유 전환 가능.

활용 예시: 한 에이전트가 라이브러리 버그를 수정하는 동안, 다른 에이전트는 새로운 API 엔드포인트를 스캐폴딩하도록 각각 병렬로 작업시킬 수 있습니다. 각 에이전트의 진행 상황을 실시간 모니터링하고, 필요시 중간 개입 및 최종 승인만 하면 됩니다.

디자인 모드

디자인 모드에서는 브라우저 UI에서 직접 요소를 선택, 강조, 주석 달기가 가능합니다. 복잡한 UI 설명 없이도 에이전트 컨텍스트로 전달할 수 있습니다.

주요 단축키:

Cmd+Shift+D: 디자인 모드 토글
Shift+drag: 영역 선택
Cmd+L: 요소를 채팅에 추가

MCP 앱: 구조화된 콘텐츠 출력

Cursor 3의 MCP 서버 도구 출력은 이제 구조화된 데이터 반환을 지원합니다. 즉, Apidog MCP 서버에서 엔드포인트, 스키마, 테스트 결과 등 API 정보를 깔끔한 데이터 객체로 에이전트에 제공합니다.

실제 스키마 데이터가 즉시 활용되므로, 에이전트가 추측 대신 명확한 타입 정보를 기반으로 코드를 생성할 수 있습니다.

워크트리, /best-of-n, 격리

/worktree: 격리된 Git 워크트리에서 안전하게 실험 및 대체 구현 가능.
/best-of-n: 여러 모델(GPT-4o, Claude, Gemini 등)로 같은 작업을 병렬 실행, 각자 독립 워크트리에서 결과 비교 후 최적안 채택.

클라우드-로컬 핸드오프

클라우드와 로컬 환경을 오가며 작업 실행이 가능합니다. 예를 들어, 클라우드에서 장기 작업을 시작하고, 필요시 로컬로 가져와 테스트할 수 있습니다.

API 개발에 미치는 영향

API 개발은 스펙, 클라이언트, 에디터, 터미널, 문서 도구 등 다양한 컨텍스트 전환이 빈번합니다. Cursor 3와 MCP 연동은 이 복잡함을 크게 줄입니다.

병렬 엔드포인트 개발

여러 엔드포인트를 각각 별도의 에이전트 인스턴스에 설명해 한번에 병렬 생성 및 검토가 가능합니다. 검사가 통과한 결과만 병합하고, 불합격 결과는 폐기하세요.

스키마 인식 코드 생성

에이전트가 OpenAPI 사양에 직접 접근하여, 실제 데이터 구조에 맞는 코드(예: Node.js/Express 핸들러, TypeScript 인터페이스 등)를 자동 생성합니다. 추측이 아닌 실시간 사양 기반 코드가 곧바로 나옵니다.

에디터 내 계약 테스트

에이전트는 터미널 명령 실행을 지원하므로, Apidog CLI와 통합해 코드 생성 후 즉시 테스트 시나리오를 자동 실행할 수 있습니다.

apidog run --scenario <test-id> --env <env>

테스트 결과가 실패하면 에이전트가 자동으로 수정 루프에 진입합니다.

항상 최신 상태를 유지하는 문서

에이전트가 API 문서와 코드의 불일치를 자동 감지하고, 실시간으로 수정 제안을 제공합니다. 반복적인 문서 동기화 작업이 자동화됩니다.

변하지 않은 것

Cursor 3는 QA 플랫폼이 아니므로 인증, 성능 등 테스트의 모든 책임을 대체하지 않습니다. MCP 구조화 출력은 Apidog MCP 서버 등 일부 MCP 서버에서만 지원됩니다.

Cursor 3 + Apidog MCP 서버: 실전 워크플로우

설정

Cursor 설정에 Apidog MCP 서버를 추가합니다. 예시:

{
  "mcpServers": {
    "apidog": {
      "command": "npx",
      "args": ["-y", "@apidog/mcp-server@latest"],
      "env": {
        "APIDOG_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

토큰은 Apidog 계정 설정 > API 액세스 토큰에서 발급.

워크플로우: 사양에서 새 엔드포인트 스캐폴딩

Apidog 프로젝트에서 POST /invoices 등 신규 엔드포인트 사양 및 테스트 시나리오 작성
에이전트 창에서 작업을 지정
"Apidog 프로젝트에서 POST /invoices 엔드포인트를 찾아 요청 및 응답 스키마를 읽고, Node.js/Express 핸들러를 생성하세요. 테스트 시나리오를 실행해 통과 여부를 확인하세요."
에이전트가 get_endpoint_detail로 스키마를 읽고, 코드를 생성, apidog run --scenario invoice-creation-test --env staging으로 테스트 실행, 오류시 자동 패치
최종 코드를 검토 후 병합

복잡한 엔드포인트와 /best-of-n

세 모델의 에이전트가 각각 동일한 Apidog 사양을 기반으로 구현을 생성하고, Cursor 워크트리 뷰에서 결과를 비교—최적의 구현을 선택하세요.

문서 동기화 유지

"POST /invoices에 대한 Apidog 문서를 코드와 비교해 불일치가 있다면 표시하세요. 코드 응답 형식이 다르면 사양을 업데이트하세요."

에이전트가 MCP 도구로 두 소스를 읽고, 실시간 비교해 동기화 작업을 자동화합니다.

Apidog의 MCP 서버 연동 및 CLI 자동화 파이프라인 구축은 추가 가이드(내부: apidog mcp 서버 개요, cli 시작하기 등)를 참고하세요.

실용적인 설정: 바로 시작하기

1. Cursor 최신 버전 설치

cursor.com에서 최신 버전을 다운로드, Cmd+Shift+P로 "Agents Window" 실행 확인.

2. Apidog 액세스 토큰 발급

Apidog 로그인 > 계정 설정 > API 액세스 토큰에서 읽기 권한 토큰 생성 및 복사.

3. Cursor에 Apidog MCP 서버 추가

{
  "mcpServers": {
    "apidog": {
      "command": "npx",
      "args": ["-y", "@apidog/mcp-server@latest"],
      "env": {
        "APIDOG_ACCESS_TOKEN": "your_token_here",
        "APIDOG_PROJECT_ID": "your_project_id"
      }
    }
  }
}

프로젝트 ID는 Apidog URL에서 확인. 저장 후 Cursor 재시작.

4. 연결 테스트

에이전트 창에서 "내 Apidog 프로젝트의 엔드포인트를 나열하세요."라고 입력, 엔드포인트 목록이 반환되면 정상 연결.

5. Apidog CLI 설치 및 구성

npm install -g apidog-cli

apidog -v로 설치 확인. Apidog 내의 시나리오 CLI 명령을 복사해 Cursor 통합 터미널 또는 에이전트 워크플로우에 바로 적용.

6. 첫 MCP 기반 에이전트 작업 실행

예시 프롬프트: "Apidog에서 User 객체 스키마를 찾아 동일한 TypeScript 인터페이스를 생성하세요."
실제 스키마와 결과를 확인해 통합 상태를 검증하세요. 이후 코딩, 테스트, 문서화 자동화 루프를 자유롭게 확장할 수 있습니다.

마무리

Cursor 3는 AI 에이전트 중심의 개발 환경으로 전환해 API 개발을 병렬화하고, 사양 기반 코드 생성 및 테스트 자동화까지 실질적으로 구현할 수 있게 합니다. Apidog MCP 서버와의 구조화 데이터 연동으로, 개발자는 반복적인 수정 없이, 실제 사양에 맞는 코드를 빠르게 얻고, 문서와 코드의 동기화도 자동화할 수 있습니다.

이제 Cursor 3와 Apidog MCP, CLI를 조합해 일상적인 API 개발 워크플로우를 자동화된 루프로 전환해보세요.

자주 묻는 질문

Cursor 3가 기존 IDE 인터페이스를 대체하나요?

아니요. 에이전트 창이 추가된 것이며, 기존 IDE 기능도 함께 사용 가능합니다.

Cursor 3와 이전 버전의 차이점은 무엇인가요?

아키텍처 중심이 에디터에서 에이전트로 전환. 병렬 실행, 클라우드-로컬 핸드오프, 디자인 모드, /worktree, /best-of-n 등 신규 명령 및 인터페이스 추가.

Apidog MCP 서버는 Cursor 3에 어떻게 연결하나요?

Cursor 설정 > MCP에서 Apidog MCP 서버를 추가하면, 에이전트가 직접 API 엔드포인트, 스키마, 테스트 시나리오를 호출형 도구로 읽을 수 있습니다. 구조화된 데이터로 타입 정보까지 자동 반영됩니다.

Cursor 3 에이전트가 Apidog 테스트 시나리오를 자동으로 실행할 수 있나요?

네, Apidog CLI와 연동하면 에이전트가 터미널 명령을 통해 테스트 시나리오를 실행, 결과를 판독해 코드까지 자동 수정하는 피드백 루프를 구축할 수 있습니다.

에이전트 창을 사용하려면 유료 플랜이 필요한가요?

에이전트 창은 무료 플랜에서도 사용 가능. 단, 클라우드 에이전트 실행(오프라인 연속 작업 등)은 유료 플랜에서 지원됩니다. 자세한 플랜 정보는 cursor.com/pricing 참고.

Gemma 4 API 백엔드 실행 방법

Rihpig — Fri, 03 Apr 2026 02:34:34 +0000

요약: Google은 2026년 4월 Gemma 4를 출시했습니다. Gemma 4는 Apache 2.0 라이선스로 배포되는 네 가지 오픈 모델 제품군으로, 표준 벤치마크에서 동급 대비 20배 이상 큰 모델을 능가하는 성능을 제공합니다. Google AI Studio, Vertex AI에서 Gemma 4 API를 호출하거나 Ollama, vLLM을 통해 로컬에서 활용할 수 있습니다. Apidog의 Smart Mock 기능을 함께 사용하면 단일 목 규칙 없이 OpenAPI 스키마 기반의 실제와 같은 API 응답을 자동 생성할 수 있습니다.

지금 Apidog을 사용해보세요

소개

대부분의 오픈 소스 AI 모델은 기능성과 배포 용이성 사이에서 선택을 강요합니다. 노트북에서 실행하기엔 너무 크거나, 다단계 추론이 불가능할 정도로 작은 경우가 많습니다. Gemma 4는 이 기존 한계를 해결합니다.

Gemma 4는 Google DeepMind의 역대 가장 강력한 오픈 모델 제품군입니다. 31B Dense 모델은 Arena AI 리더보드에서 모든 오픈 모델 중 3위, 26B MoE 모델은 6위를 차지했습니다. 두 모델 모두 단일 80GB GPU에서 실행이 가능하고, E2B/E4B 경량 모델은 모바일·엣지 디바이스에서 오프라인 작동이 가능합니다.

API 개발 관점에서 Gemma 4는 함수 호출, 구조화된 JSON 출력, 256K 컨텍스트 창을 기본 지원합니다. 테스트 데이터 생성, 목(mock) 작성, API 응답 분석 등 AI 기반 API 도구 구축에 즉시 활용 가능합니다.

💡Gemma 4로 개발 중이고, AI가 생성한 응답을 OpenAPI 스펙에 맞게 검증해야 한다면 Apidog의 Smart Mock 엔진을 활용하세요. API 정의에서 스키마 기반의 목(mock) 응답을 자동 생성해줍니다. 별도의 목 규칙 작성이 필요 없습니다. Smart Mock이 스키마를 읽고 실용적인 테스트 데이터를 즉시 생성합니다. Apidog을 무료로 다운로드해 Gemma 4 API 워크플로우에 연동해보세요.

Gemma 4란 무엇이며, 새로운 점은?

Gemma 4는 Google DeepMind의 4세대 오픈 언어 모델입니다. "Gemma"는 라틴어로 "보석"을 의미하며, 2024년 초 첫 번째 시리즈가 등장한 이후 4억 회 이상 다운로드되었습니다. 커뮤니티는 10만 개 이상의 변형을 만들었고, Google은 이를 "Gemmaverse"로 부릅니다.

Gemma 4는 Apache 2.0 라이선스로 배포됩니다. 상업적 제약 없이 사용, 수정, 배포가 가능해 기업과 스타트업에 실질적 이점을 제공합니다.

주요 혁신은 "매개변수당 지능"입니다. 31B Dense 모델은 GPT-4, Claude 3 Sonnet과 유사한 기능을 훨씬 적은 컴퓨팅 비용으로 제공합니다. Arena AI(2026년 4월 기준)에서 Gemma 4 31B는 600B+ 파라미터 모델도 능가합니다.

Gemma 3 대비 핵심 개선점:

네이티브 멀티모달 입력: 이미지, 비디오(모든 모델), 오디오(E2B/E4B) 입력 지원
더 긴 컨텍스트 창: E2B/E4B: 128K, 26B/31B: 256K 토큰
에이전트 워크플로우 지원: 함수 호출, 구조화된 JSON 출력, 시스템 프롬프트 지원
고급 추론: 수학·다단계 이행 등에서 Gemma 3 대비 대폭 개선
140+개 언어 지원: 글로벌 API에 즉시 활용 가능
Apache 2.0 라이선스: 완전한 상업적 자유 보장

Gemma 4 모델 변형 및 기능

Google은 4가지 크기로 Gemma 4를 출시했습니다. 각 모델은 타겟 하드웨어 계층이 다릅니다.

모델	매개변수	활성 매개변수 (추론)	컨텍스트	최적 용도
E2B	유효 2B	약 2B	128K	모바일, IoT, 오프라인 엣지
E4B	유효 4B	약 4B	128K	휴대폰, Raspberry Pi, Jetson Orin
26B MoE	총 26B	약 3.8B 활성	256K	지연 시간에 민감한 서버 작업
31B Dense	31B	31B	256K	최고 품질, 연구, 미세 조정

E2B/E4B는 MoE(Mixture of Experts) 아키텍처로 일부 파라미터만 활성화해 저전력·저RAM 환경(모바일, IoT 등)에 최적화되어 있습니다. 26B MoE는 3.8B 활성 파라미터로 빠른 추론과 품질의 균형을 제공합니다. 31B Dense는 최고 품질, 복잡한 API 테스트 및 미세 조정에 적합합니다.

모든 모델 변형은 함수 호출과 JSON 출력 모드를 지원하므로 API 자동화, 목(mock) 생성, 테스트 등 다양한 개발 워크플로우에 즉각 적용할 수 있습니다.

Gemma 4 API 설정: 단계별 안내

Gemma 4는 세 가지 주요 방법으로 호출할 수 있습니다: Google AI Studio(가장 빠름), Vertex AI(기업용), Ollama/vLLM(로컬 배포). 각 방법별 구현 절차는 다음과 같습니다.

옵션 1: Google AI Studio (프로토타이핑)

Google AI Studio에서 무료 계정 생성 후 API 키를 발급받으세요.

pip install google-genai

기본 텍스트 호출 예시:

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

model = genai.GenerativeModel("gemma-4-31b-it")

response = model.generate_content(
    "Generate a JSON object for a user account with id, email, and created_at fields."
)

print(response.text)

구조화된 JSON 응답이 필요하다면 response_mime_type을 사용하세요:

import google.generativeai as genai
import json

genai.configure(api_key="YOUR_API_KEY")

model = genai.GenerativeModel(
    "gemma-4-31b-it",
    generation_config={"response_mime_type": "application/json"}
)

prompt = """
Generate 3 sample user objects for an e-commerce API. 
Each user should have: id (integer), email (string), username (string), 
created_at (ISO 8601 timestamp), and subscription_tier (free|pro|enterprise).
Return as a JSON array.
"""

response = model.generate_content(prompt)
users = json.loads(response.text)
print(json.dumps(users, indent=2))

옵션 2: Ollama로 로컬 배포

Ollama를 설치한 후 모델을 가져옵니다.

ollama pull gemma4
ollama serve

OpenAI 호환 API 예시:

import requests
import json

response = requests.post(
    "http://localhost:11434/api/chat",
    json={
        "model": "gemma4",
        "messages": [
            {
                "role": "user",
                "content": "Generate a valid JSON response for a REST API /products endpoint. Include id, name, price, and stock fields."
            }
        ],
        "stream": False
    }
)

result = response.json()
print(result["message"]["content"])

옵션 3: 함수 호출 기반 API 오케스트레이션

Gemma 4의 네이티브 함수 호출로 도구를 정의하고 API 워크플로우를 자동화할 수 있습니다.

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

tools = [
    {
        "function_declarations": [
            {
                "name": "get_api_schema",
                "description": "Retrieve the OpenAPI schema for a given endpoint path",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "endpoint_path": {
                            "type": "string",
                            "description": "The API endpoint path, e.g. /users/{id}"
                        },
                        "method": {
                            "type": "string",
                            "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"]
                        }
                    },
                    "required": ["endpoint_path", "method"]
                }
            }
        ]
    }
]

model = genai.GenerativeModel("gemma-4-31b-it", tools=tools)

response = model.generate_content(
    "I need to test the GET /users/{id} endpoint. What schema should the response follow?"
)

# 함수 호출 여부 확인
if response.candidates[0].content.parts[0].function_call:
    fc = response.candidates[0].content.parts[0].function_call
    print(f"Model called function: {fc.name}")
    print(f"With args: {dict(fc.args)}")

이 방식으로 Gemma 4 기반의 에이전트 API 테스트 파이프라인을 쉽게 구축할 수 있습니다.

Gemma 4로 AI 기반 API 목(mock) 구축하기

Gemma 4는 실제와 같은 목(mock) 데이터 자동 생성에 매우 적합합니다. 백엔드 없이 프론트엔드 개발, 엣지 케이스 테스트 등에서 실질적으로 활용할 수 있습니다.

OpenAPI 스키마 기반 목 데이터 생성 예시:

import google.generativeai as genai
import json

genai.configure(api_key="YOUR_API_KEY")

model = genai.GenerativeModel(
    "gemma-4-31b-it",
    generation_config={"response_mime_type": "application/json"}
)

schema = {
    "type": "object",
    "properties": {
        "id": {"type": "integer"},
        "order_number": {"type": "string", "pattern": "^ORD-[0-9]{6}$"},
        "status": {"type": "string", "enum": ["pending", "shipped", "delivered", "cancelled"]},
        "total": {"type": "number", "minimum": 0},
        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "product_id": {"type": "integer"},
                    "quantity": {"type": "integer", "minimum": 1},
                    "unit_price": {"type": "number"}
                }
            }
        },
        "created_at": {"type": "string", "format": "date-time"}
    }
}

prompt = f"""
Generate 5 realistic mock responses for an order management API.
Each response must conform exactly to this JSON Schema:
{json.dumps(schema, indent=2)}

Make the data realistic: use realistic prices, product IDs, and varied statuses.
Return as a JSON array of 5 order objects.
"""

response = model.generate_content(prompt)
mock_orders = json.loads(response.text)
print(json.dumps(mock_orders, indent=2))

Gemma 4는 JSON Schema 제약을 이해하므로, 열거형·패턴·숫자 범위 제약까지 충실하게 목 데이터를 생성합니다. 이 방식으로 모든 OpenAPI 응답 스키마에 대해 실제와 같은 목 데이터를 자동화할 수 있습니다.

고급 목킹이 필요하다면, 조건부 로직(예: 특정 ID에 대해 오류 응답 반환 등)도 프롬프트에 포함해 요청별 상황을 반영할 수 있습니다. 256K 컨텍스트 창을 활용하면 한 번에 여러 엔드포인트 목 응답도 생성 가능합니다.

실전 워크플로우 예시: Apidog 컬렉션을 OpenAPI로 내보내 프롬프트에 붙여넣고, Gemma 4에 엔드포인트별 테스트 케이스 10개씩 요청하세요. 단시간 내에 방대한 목 데이터셋을 구축할 수 있습니다.

Apidog으로 Gemma 4 API 응답 테스트하기

Gemma 4가 생성한 데이터를 API 파이프라인에 적용하려면, 응답이 스키마와 일치하는지 자동 검증이 필요합니다. Apidog의 테스트 시나리오(Test Scenarios)를 활용하세요.

실행 절차는 다음과 같습니다.

Gemma 4 API 엔드포인트를 Apidog에 추가: 프로젝트 내 새 엔드포인트 생성 → URL 설정 → 예상 응답 스키마 등록
Smart Mock으로 기준 응답 생성: 스키마 기반 자동 목 데이터를 생성해 실제 응답 구조를 미리 확인
테스트 시나리오 생성: Apidog 테스트 모듈에서 Gemma 4 API 호출, 응답 검증을 단계별로 설정
단언(assertion) 설정: 상태 코드, 헤더, JSON 필드 존재 여부, 파싱된 결과의 스키마 일치 여부를 검증
데이터 기반 테스트 실행: CSV/JSON 파일로 다양한 프롬프트 변형을 불러와 대량 테스트 자동화

Apidog의 변수 추출, 다단계 워크플로우, CLI·CI/CD 연동을 활용하면 Gemma 4 기반 API 테스트를 완전 자동화할 수 있습니다.

실제 사용 사례

API 테스트 데이터 생성: OpenAPI 스키마와 JSON 출력 모드로 수백 건의 현실적인 테스트 레코드 자동 생성
지능형 API 목킹: 정적 목 서버 대신, Gemma 4로 쿼리별 동적·상황별 응답 생성
API 문서 생성: 코드베이스 전체를 프롬프트에 넣고 문서화되지 않은 엔드포인트의 OpenAPI 문서 자동 생성
응답 스키마 유효성 검사: Gemma 4로 API 응답 분석 및 스키마 위반 자동 탐지
자동 회귀 테스트 작성: API 사양+버그 리포트 입력 → 재현 가능한 회귀 테스트 케이스 자동 생성

API 사용을 위한 Gemma 4 vs 다른 오픈 모델

모델	매개변수	컨텍스트	JSON 출력	함수 호출	라이선스
Gemma 4 31B	31B	256K	네이티브	네이티브	Apache 2.0
Gemma 4 26B MoE	26B (3.8B 활성)	256K	네이티브	네이티브	Apache 2.0
Llama 3.3 70B	70B	128K	프롬프트를 통해	프롬프트를 통해	Llama 커뮤니티
Mistral 7B	7B	32K	프롬프트를 통해	제한적	Apache 2.0
Qwen 2.5 72B	72B	128K	네이티브	네이티브	Apache 2.0

API 툴링에는 네이티브 JSON 출력, 함수 호출 지원, 긴 컨텍스트 창이 중요합니다. Gemma 4 31B/26B는 모두 해당 기능을 기본 제공하며, 실행 비용도 최적화되어 있습니다.

Llama 3.3 70B는 강력하지만 컴퓨팅 리소스가 2배 이상 필요합니다. Mistral 7B는 빠르지만, 컨텍스트 창과 JSON/함수 호출 지원이 제한적입니다. Qwen 2.5 72B는 다국어에 강점이 있으나, 역시 대형 하드웨어가 필수입니다. Gemma 4의 Apache 2.0 라이선스는 상업적 배포에 있어 가장 명확합니다.

실제 사용 시, 지연 시간에 민감하면 Gemma 4 26B MoE, 최고 품질 출력이 필요하다면 31B Dense를 선택하세요.

결론

Gemma 4는 API 툴링 구축을 위한 신뢰성 높은 오픈 소스 대안입니다. Apache 2.0 라이선스, 네이티브 함수 호출/JSON 출력 지원, 다양한 하드웨어 계층 지원 등으로 API 워크플로우에 쉽게 통합할 수 있습니다.

AI 생성 데이터와 API 유효성 검증을 연결하려면 Gemma 4와 Apidog을 조합하세요. Gemma 4로 목 데이터 생성, Apidog Smart Mock으로 스키마 기반 프로토타입, 테스트 시나리오로 계약 일치 검증까지 한 번에 구축할 수 있습니다.

FAQ

Gemma 4란 무엇인가요? Gemma 4는 2026년 4월 출시된 Google DeepMind 오픈 언어 모델 제품군입니다. E2B, E4B, 26B MoE, 31B Dense 네 가지 버전이 있으며, Apache 2.0 라이선스가 적용됩니다. 31B 모델은 Arena AI 리더보드에서 오픈 모델 3위입니다.

Gemma 4는 무료로 사용할 수 있나요? 모델 가중치는 Apache 2.0에 따라 무료 다운로드/사용이 가능합니다. 직접 실행 시 컴퓨팅 비용만 부담하면 되며, Google AI Studio의 경우 무료 티어와 유료 요금제가 있습니다. Vertex AI는 Google Cloud 요금이 적용됩니다.

Gemma 4는 구조화된 JSON을 출력할 수 있나요? 네. Google Generative AI SDK의 response_mime_type: "application/json" 옵션으로 네이티브 JSON 출력이 가능합니다. API 통합 시 항상 유효한 JSON을 자동 파싱할 수 있습니다.

API 개발에 있어 Gemma 4와 GPT-4o의 차이는? GPT-4o는 로컬 배포가 불가능하고, API 비용이 높은 독점 모델입니다. Gemma 4 31B는 무료 로컬 배포가 가능하며, 벤치마크 역시 경쟁력이 높습니다. 데이터 프라이버시·비용 제어가 필요하다면 Gemma 4가 실용적입니다.

내 API 데이터로 Gemma 4를 미세 조정할 수 있나요? 네. Google AI Studio, Vertex AI, Hugging Face TRL 등에서 미세 조정 지원합니다. 도메인별 OpenAPI 스키마/응답 패턴에 특화된 모델을 만들 수 있습니다.

Gemma 4를 로컬에서 실행하려면 어떤 하드웨어가 필요한가요? 31B/26B는 bfloat16 형식에서 80GB H100 GPU에 적합합니다. 양자화 버전은 16–24GB VRAM의 소비자 GPU에서도 실행됩니다. E4B/E2B는 Raspberry Pi, Jetson 등 모바일·엣지 디바이스에서도 작동합니다.

Gemma 4는 함수 호출을 지원하나요? 네. 모든 모델에서 함수 호출을 네이티브로 지원합니다. 도구를 JSON 스키마로 정의하면, 모델이 호출 시기를 판단하고 구조화된 인수를 반환합니다.

Gemma 4 API 응답을 자동 테스트하려면? Apidog 테스트 시나리오(Test Scenarios)로 워크플로우를 만드세요. Gemma 4 API 엔드포인트 등록 → 요청/응답 검증 단계 추가 → 단언(assertion) 설정 → 로컬/CLI/CI/CD에서 자동 실행이 가능합니다.

Qwen3.6-Plus API: 터미널 벤치마크에서 Claude 능가

Rihpig — Thu, 02 Apr 2026 09:28:12 +0000

요약

Qwen3.6-Plus가 공식 출시되었습니다. SWE-bench Verified에서 78.8%, Terminal-Bench 2.0에서 61.6%를 기록해 Claude Opus 4.5를 능가합니다. 1M 토큰 컨텍스트 윈도우, 에이전트 루프를 위한 새로운 preserve_thinking 매개변수를 제공하며, OpenAI 호환 API로 Claude Code, OpenClaw, Qwen Code와 바로 연동됩니다.

Apidog를 지금 사용해보세요

미리보기에서 정식 출시까지

OpenRouter의 Qwen 3.6 Plus 미리보기를 경험했다면, 이 모델의 성능을 이미 확인하셨을 겁니다. 미리보기는 3월 30일에 대기 없이 무료로 공개되어 이틀간 40만 건 요청, 4억 토큰을 처리했습니다.

정식 출시는 프로덕션 수준의 안정성, SLA 기반 가동 시간, API 매개변수 확장(특히 에이전트 작업을 위한 기능 강화)을 제공합니다. 본 가이드에서는 주요 변경점, API 호출법, Apidog를 통한 통합 테스트 방법을 실전 위주로 다룹니다.

Qwen3.6-Plus란 무엇인가

Qwen3.6-Plus는 Alibaba Qwen팀이 제공하는 Mixture-of-Experts(MoE) 모델입니다. Qwen3.5 시리즈처럼 희소 활성화(sparse activation) 구조로, 밀집 모델 대비 낮은 연산 비용에 동급 이상의 성능을 제공합니다.

주요 스펙:

1백만 토큰 컨텍스트 윈도우(기본)
연쇄 사고 추론 (CoT) 지원
에이전트 작업용 preserve_thinking 매개변수
네이티브 멀티모달(이미지, 비디오, 문서) 지원
OpenAI/Anthropic 호환 API

곧 오픈소스 소형 변형 모델(가중치 공개)도 출시 예정입니다.

벤치마크 결과

코딩 에이전트

Qwen3.6-Plus는 SWE-bench 작업에선 Claude Opus 4.5에 근소하게 뒤지지만, 터미널 작업에서는 모든 모델을 앞섭니다.

Terminal-Bench 2.0은 32코어, 48GB RAM 환경에서 3시간 내 실전 셸 작업을 평가합니다. Qwen3.6-Plus가 61.6%, Claude Opus 4.5가 59.3%로 실제 개발 시나리오에서 의미 있는 차이를 보입니다.

일반 에이전트 및 도구 사용

벤치마크	Claude Opus 4.5	Qwen3.6-Plus
TAU3-Bench	70.2%	70.7%
DeepPlanning	33.9%	41.5%
MCPMark	42.3%	48.2%
MCP-Atlas	71.8%	74.1%
WideSearch	76.4%	74.3%

MCPMark는 GitHub MCP v0.30.3 도구 호출을 평가합니다. Qwen3.6-Plus의 DeepPlanning/ MCPMark 우위는 장기 플래닝 및 툴 통합 시 강점입니다.

추론 및 지식

벤치마크	Claude Opus 4.5	Qwen3.6-Plus
GPQA	87.0%	90.4%
LiveCodeBench v6	84.8%	87.1%
IFEval strict	90.9%	94.3%
MMLU-Pro	89.5%	88.5%

GPQA(대학원 수준 과학 추론), IFEval strict(출력 형식/제약 준수) 부문에서 Qwen3.6-Plus가 앞섭니다.

멀티모달

벤치마크	Qwen3.6-Plus	참고
OmniDocBench 1.5	91.2%	표에서 1위
RefCOCO avg	93.5%	표에서 1위
We-Math	89.0%	표에서 1위
CountBench	97.6%	표에서 1위
OSWorld-Verified	62.5%	Claude(66.3%)에 뒤짐

OSWorld-Verified(데스크탑 사용)는 Claude가 우위, 공간/문서 이해는 Qwen3.6-Plus가 선두입니다.

API 호출 방법

Qwen3.6-Plus는 Alibaba Cloud Model Studio에서 사용 가능합니다. API 키는 modelstudio.alibabacloud.com에서 발급받으세요.

기본 API 엔드포인트:

싱가포르: https://dashscope-intl.aliyuncs.com/compatible-mode/v1
베이징: https://dashscope.aliyuncs.com/compatible-mode/v1
미국 버지니아: https://dashscope-us.aliyuncs.com/compatible-mode/v1

스트리밍을 사용한 기본 호출

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["DASHSCOPE_API_KEY"],
    base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)

completion = client.chat.completions.create(
    model="qwen3.6-plus",
    messages=[{"role": "user", "content": "Review this Python function and find bugs."}],
    extra_body={"enable_thinking": True},
    stream=True
)

reasoning = ""
answer = ""
is_answering = False

for chunk in completion:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta
    if hasattr(delta, "reasoning_content") and delta.reasoning_content:
        if not is_answering:
            reasoning += delta.reasoning_content
    if delta.content:
        if not is_answering:
            is_answering = True
        answer += delta.content
        print(delta.content, end="", flush=True)

preserve_thinking 매개변수

정식 버전에서는 preserve_thinking 옵션이 추가되었습니다.

preserve_thinking: true로 설정하면, 이전 대화 모든 턴의 연쇄 추론 내용이 보존됩니다.
다단계 에이전트/오케스트레이션에서는 반드시 활성화하세요.
기본값은 비활성화(토큰 절약 목적)입니다.

completion = client.chat.completions.create(
    model="qwen3.6-plus",
    messages=conversation_history,
    extra_body={
        "enable_thinking": True,
        "preserve_thinking": True, # 턴 전체 추론 체인 유지
    },
    stream=True
)

Qwen3.6-Plus를 Claude Code와 함께 사용

Qwen API는 Anthropic 프로토콜을 지원합니다. 환경 변수 세팅만으로 Claude Code에서 바로 사용 가능합니다.

npm install -g @anthropic-ai/claude-code

export ANTHROPIC_MODEL="qwen3.6-plus"
export ANTHROPIC_SMALL_FAST_MODEL="qwen3.6-plus"
export ANTHROPIC_BASE_URL=https://dashscope-intl.aliyuncs.com/apps/anthropic
export ANTHROPIC_AUTH_TOKEN=your_dashscope_api_key

claude

Qwen3.6-Plus를 OpenClaw와 함께 사용

OpenClaw(구 Moltbot/Clawdbot) 오픈소스 코딩 에이전트를 설치하고 Model Studio 엔드포인트로 설정하세요.

# Node.js 22+ 필요
curl -fsSL https://molt.bot/install.sh | bash

export DASHSCOPE_API_KEY=your_key
openclaw dashboard

~/.openclaw/openclaw.json에 아래 설정을 병합하세요.

{
  "models": {
    "providers": [{
      "name": "alibaba-coding-plan",
      "baseUrl": "https://coding-intl.dashscope.aliyuncs.com/v1",
      "apiKey": "${DASHSCOPE_API_KEY}",
      "models": [{"id": "qwen3.6-plus", "reasoning": true}]
    }]
  },
  "agents": {
    "defaults": {"models": ["qwen3.6-plus"]}
  }
}

Qwen3.6-Plus를 Qwen Code와 함께 사용

Qwen Code는 Qwen 전용 오픈소스 터미널 에이전트입니다. OAuth 로그인 시 하루 1,000회 무료 호출이 제공됩니다.

npm install -g @qwen-code/qwen-code@latest
qwen
# /auth 입력 후 무료 티어 활성화

preserve_thinking이 에이전트 동작을 변경하는 이유

대부분의 LLM API는 각 턴을 독립적으로 처리합니다. 단일 Q&A는 문제 없지만, 다단계 에이전트에서는 이전 추론을 잃어버려 일관성이 깨집니다.

preserve_thinking을 활성화하면, 모든 턴의 연쇄 추론이 다음 응답 생성 시 반영됩니다. 즉, 8단계 에이전트가 2, 4, 6단계의 분석까지 파악, 더 일관된 결정을 내릴 수 있습니다.

Alibaba 벤치마크에 따르면, 중복 추론도 줄어들고, 장기 워크플로우에서 토큰 소모도 감소합니다.

에이전트 루프 예시:

conversation = []

def agent_step(user_message, preserve=True):
    conversation.append({"role": "user", "content": user_message})

    response = client.chat.completions.create(
        model="qwen3.6-plus",
        messages=conversation,
        extra_body={
            "enable_thinking": True,
            "preserve_thinking": preserve,
        },
        stream=False
    )

    message = response.choices[0].message
    conversation.append({"role": "assistant", "content": message.content})
    return message.content

# 다단계 코드 리뷰 에이전트 예시
result = agent_step("Analyze the auth module for security issues.")
result = agent_step("Now suggest fixes for the top 3 issues you found.")
result = agent_step("Write tests that validate each fix.")

preserve_thinking이 없으면 3단계에서 1단계의 결과를 모델이 모릅니다. 이 기능으로 연쇄 추론이 온전히 유지됩니다.

무엇에 가장 적합한가

리포지토리 수준 버그 수정: SWE-bench Verified 78.8%, Pro 56.6%. 자동 코드 수정/검토 파이프라인에 적합.
터미널 자동화: Terminal-Bench 2.0 1위. 셸 기반 다단계 파일/프로세스 작업, 빌드 파이프라인.
MCP 도구 호출: MCPMark 48.2%(최고). MCP 연동 자동화에 최적.
장문 컨텍스트 문서 분석: 1M 토큰 윈도우로 코드베이스 전체/대규모 문서 분석에 유리.
프론트엔드 코드 생성: QwenWebBench 기준 Claude와 동급(1501.7 vs 1517.9 Elo).
다국어: WMT24++ 84.3%(최고), 23개 언어 MAXIFE 88.2%. 비영어권 사용에 강함.

Apidog로 Qwen3.6-Plus API 호출 테스트하기

Qwen3.6-Plus 엔드포인트는 OpenAI와 호환되므로 Apidog에서 바로 테스트할 수 있습니다.

POST 엔드포인트: https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions
환경변수로 API 키 추가: Authorization: Bearer {{DASHSCOPE_API_KEY}}

응답 어설션 예시:

pm.test("Response contains choices", () => {
  const body = pm.response.json();
  pm.expect(body).to.have.property("choices");
  pm.expect(body.choices[0].message.content).to.be.a("string").and.not.empty;
});

pm.test("No empty reasoning when thinking enabled", () => {
  const choice = pm.response.json().choices[0];
  if (choice.message.reasoning_content !== undefined) {
    pm.expect(choice.message.reasoning_content).to.not.be.empty;
  }
});

팁:

개발 중에는 Smart Mock으로 응답을 시뮬레이션해 토큰 소모 없이 에이전트 로직을 빠르게 검증할 수 있습니다.
다단계 에이전트라면 여러 요청을 테스트 시나리오로 연결해 각 단계의 응답 구조와 preserve_thinking 유지 여부를 확인하세요.

Apidog를 무료로 다운로드하여 바로 시작하세요.

다음은 무엇인가

Qwen팀은 수일 내 오픈소스 소형 변형 모델(희소 MoE, Apache 2.0 가중치)을 출시할 예정입니다.

로드맵 주요 목표:

복잡한 다중 파일 문제 해결을 위한 장기 리포지토리 작업
GUI 에이전트 및 시각적 코딩이 부가가치가 아닌 기본 기능으로 자리잡는 멀티모달 에이전트

Qwen3.5 오픈소스 모델은 출시 즉시 많이 배포된 자체호스팅 모델이 되었습니다. Qwen3.6도 이 패턴을 따를 가능성이 높습니다.

결론

Qwen3.6-Plus는 Claude Opus 4.5와의 격차를 좁혔으며, 터미널 자동화, MCP 도구 호출, 장기 플래닝에선 확실한 우위를 점합니다. 1M 토큰 컨텍스트, Anthropic 프로토콜 지원, preserve_thinking 옵션은 실제 프로덕션 에이전트 구축에 실질적인 장점입니다.

OpenRouter의 무료 미리보기는 모델 평가에 적합했고, 공식 API는 안정성 및 에이전트 중심 기능을 강화했습니다.

Apidog은

OpenAI 호환 엔드포인트 테스트
응답 어설션 작성
Smart Mock으로 오프라인 개발
모델/버전 교체 시 회귀 테스트

등 API 통합 품질 확보에 적합합니다.

자주 묻는 질문

Qwen3.6-Plus와 미리보기 버전의 차이점은?

미리보기(qwen/qwen3.6-plus-preview)는 2026년 3월 30일 OpenRouter에 출시. 정식 출시는 preserve_thinking 매개변수, SLA 기반 가동 시간, Model Studio 지원 추가. 소형 오픈소스 모델도 곧 출시.

preserve_thinking은 언제 써야 하나요?

기본은 현재 턴 추론만 보존. preserve_thinking: true로 설정 시 모든 이전 턴의 연쇄 추론을 유지. 다단계 에이전트 루프 등 과거 추론이 행동에 영향을 미치는 경우 반드시 사용.

Qwen3.6-Plus와 Claude Opus 4.5 비교?

Claude Opus 4.5가 SWE-bench Verified(80.9% vs 78.8%), OSWorld-Verified(66.3% vs 62.5%)에서 우위. Qwen3.6-Plus는 Terminal-Bench 2.0(61.6% vs 59.3%), MCPMark(48.2% vs 42.3%), DeepPlanning(41.5% vs 33.9%), GPQA(90.4% vs 87.0%)에서 앞섬.

Qwen3.6-Plus를 Claude Code와 함께 쓸 수 있나요?

가능. ANTHROPIC_BASE_URL을 Dashscope Anthropic 호환 엔드포인트로, ANTHROPIC_MODEL을 qwen3.6-plus로, ANTHROPIC_AUTH_TOKEN을 Dashscope API 키로 설정.

Qwen3.6-Plus는 오픈소스인가요?

호스팅 API 모델은 오픈 웨이트가 아님. 곧 오픈소스 소형 변형 모델이 공개됩니다.

무료 액세스는 어떻게?

Qwen Code 설치(npm install -g @qwen-code/qwen-code@latest), 실행 후 /auth 입력, OAuth 로그인 시 하루 1,000건 무료 API 호출 제공.

컨텍스트 윈도우 크기는?

기본 1백만 토큰. 공식 벤치 일부는 256K 기준이지만, API 기본값은 1M.

배포 전 API 통합 테스트 방법은?

엔드포인트를 Apidog로 가져오고, 환경 변수로 API 키 추가, 응답 어설션 작성, 오프라인 개발 시 Smart Mock 사용. 여러 요청을 시나리오로 연결해 다단계 에이전트 동작을 엔드 투 엔드로 검증.

Holo3: 최고의 컴퓨터 사용 모델?

Rihpig — Thu, 02 Apr 2026 08:49:39 +0000

요약 (TL;DR)

2026년 3월 31일, H Company는 Holo3를 출시했습니다. Holo3는 전문가 혼합(mixture-of-experts) 모델로, 선도적인 데스크톱 컴퓨터 사용 벤치마크인 OSWorld-Verified에서 역대 최고 점수인 78.85%를 기록했습니다. 이 모델은 GPT-5.4와 Opus 4.6을 훨씬 저렴한 비용으로 능가합니다. API는 현재 활성화되어 있으며, 35B 변형 모델은 Apache 2.0 라이선스 하에 HuggingFace에서 공개 가중치로 제공됩니다.

Apidog를 지금 체험해보세요

대부분의 개발자가 해결하지 못한 컴퓨터 사용 격차

API 자동화와 CI/CD 파이프라인을 구축해도, 아직 API가 없는 레거시 엔터프라이즈 소프트웨어, REST 이전의 데스크톱 앱, 그리고 여러 UI를 넘나드는 복잡한 워크플로우는 자동화가 어렵습니다.

기존 RPA 도구(UiPath, Automation Anywhere)는 UI 변경에 매우 취약한 화면 좌표 스크립트에 의존하며, 결국 수동 작업으로 돌아가는 경우가 많습니다.

컴퓨터 사용 AI는 이 한계를 극복합니다. 스크린샷을 기반으로 클릭, 입력, 스크롤 등 액션을 지시할 수 있어 API가 없는 GUI 환경도 자동화할 수 있습니다. 2026년 3월, H Company가 공개한 Holo3는 이 영역에서 가장 강력한 공개 모델입니다.

💡 데스크톱 소프트웨어 자동화 워크플로우나 테스트 파이프라인을 구축 중이라면, Holo3 API 구조를 파악하는 것이 중요합니다. Apidog와 함께라면 API 설계/테스트 후 Holo3 호출을 워크플로우에 쉽게 연결할 수 있습니다.

Holo3란 무엇인가요?

Holo3는 컴퓨터 사용 모델입니다. 데스크톱 또는 브라우저의 스크린샷과 작업 지시를 입력하면, 해당 화면에서 실행할 액션(클릭, 입력, 스크롤 등)을 응답합니다. 결과를 받아 반복적으로 실행하며, 최종적으로 작업을 완료합니다.

H Company는 두 가지 변형 모델을 제공합니다:

Holo3-122B-A10B — 122B 파라미터, 10B 활성. API 전용으로 제공되며, 벤치마크 최고 성능을 기록했습니다.
Holo3-35B-A3B — 35B 파라미터, 3B 활성. Apache 2.0 라이선스로 공개 가중치 제공, 무료 등급 API 지원, 자체 호스팅 가능.

MoE(전문가 혼합) 아키텍처는 토큰당 일부 파라미터만 활성화해, 실행 비용을 크게 줄입니다. H Company는 Holo3-122B-A10B가 GPT-5.4 및 Opus 4.6 대비 작업당 비용이 더 낮다고 밝히고 있습니다.

OSWorld-Verified: 벤치마크가 실제로 측정하는 것

OSWorld-Verified는 AI 컴퓨터 사용 평가를 위한 업계 표준 벤치마크입니다. 단순 출력 평가가 아니라, 실제 컴퓨터에서 작업을 실행하여 결과를 검증합니다.

벤치마크 작업 예시:

단일 앱 작업 (파일 열기, 양식 작성 등)
교차 앱 워크플로우 (PDF 값 추출 후 이메일 전송 등)
여러 시스템을 오가며 컨텍스트를 유지하는 장기 시퀀스

Holo3-122B-A10B는 OSWorld-Verified에서 78.85%의 기록을 세웠습니다. 참고로 기존 SOTA 모델(Anthropic, OpenAI)은 60~65%대였습니다.

특히 다중 앱 작업 등 복잡한 시나리오에서 Holo3가 기존 모델 대비 높은 정확도를 보입니다.

Holo3 훈련 방식: 에이전틱 학습 플라이휠

대부분의 컴퓨터 사용 모델은 정적인 시연 데이터로 훈련됩니다. H Company는 에이전틱 학습 플라이휠이라는 연속 훈련 루프를 도입했습니다:

합성 내비게이션 데이터: 사람이 지시한 시나리오 예제로 데이터 생성
도메인 외 증강: UI 엣지 케이스, 비정상 상태 등 데이터 다양성 증대
큐레이션된 강화학습: RL 파이프라인에서 직접 작업 완료율을 극대화하는 데이터만 필터링 사용

훈련 데이터는 합성 환경 팩토리에서 생성됩니다. 이 환경은 에이전트가 실제 비즈니스 워크플로우를 경험할 수 있도록 시나리오별 웹앱/엔터프라이즈 앱을 자동 생성합니다.

이 방식 덕분에 Holo3는 같은 파라미터 규모의 다른 모델(Qwen3.5 등)보다 실제 작업에서 더 뛰어난 성능을 보입니다.

Holo3 API 호출 방법

Holo3 API는 "스크린샷 → 액션 → 반복" 패턴을 따릅니다. 실제 연동을 위한 절차는 다음과 같습니다.

1. 인증 설정

# H Company Inference API base URL
https://api.hcompany.ai/v1

# Header
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

API 키 발급 후, 무료 등급으로 Holo3-35B-A3B 사용 가능.

2. 작업과 함께 스크린샷 전송

import base64
import httpx
import pyautogui

# 스크린샷 캡처
screenshot = pyautogui.screenshot()
screenshot.save("/tmp/screen.png")

with open("/tmp/screen.png", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

response = httpx.post(
    "https://api.hcompany.ai/v1/computer-use",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "holo3-122b-a10b",
        "task": "Open the invoice folder and find the most recent PDF",
        "screenshot": image_b64,
        "screen_width": 1920,
        "screen_height": 1080
    }
)

action = response.json()
print(action)

3. 액션 파싱 및 실행

API는 다음과 같이 구조화된 액션을 반환합니다.

{
  "action_type": "click",
  "coordinate": [245, 380],
  "reasoning": "The invoice folder icon is visible at this position"
}

지원 액션: click, double_click, right_click, type, key, scroll, screenshot_request, task_complete 등.

4. 완료될 때까지 반복

def run_computer_use_task(task: str, max_steps: int = 20):
    for step in range(max_steps):
        screenshot = capture_screen()
        response = call_holo3_api(task, screenshot)
        action = response["action"]

        if action["action_type"] == "task_complete":
            print(f"Done in {step + 1} steps")
            return response["result"]

        execute_action(action)

    raise TimeoutError("Task not completed within step limit")

Apidog로 Holo3 API 호출 테스트하기

Holo3 API 통합 후, 프로덕션 자동화를 위해 반드시 안정성을 검증해야 합니다. Apidog는 이런 테스트에 최적화되어 있습니다.

엔드포인트 추가:

Apidog에서 https://api.hcompany.ai/v1/computer-use를 HTTP 요청으로 생성, API 키는 환경 변수로 관리하세요.

요청 유효성 검사:

Apidog의 테스트 어설션(assertions) 기능을 활용하면 응답 구조를 자동 검증할 수 있습니다.

// Apidog post-response script 예시
pm.test("Action type is valid", () => {
    const validActions = ["click", "type", "key", "scroll", "task_complete", "screenshot_request"];
    pm.expect(validActions).to.include(pm.response.json().action.action_type);
});

pm.test("Coordinates are within screen bounds", () => {
    const action = pm.response.json().action;
    if (action.coordinate) {
        pm.expect(action.coordinate[0]).to.be.within(0, 1920);
        pm.expect(action.coordinate[1]).to.be.within(0, 1080);
    }
});

API 목(Mock) 사용:

Apidog의 Smart Mock을 통해 실제 API 호출 없이 현실적인 Holo3 응답을 생성해, 통합 테스트나 프론트엔드 개발을 병렬로 진행할 수 있습니다.

테스트 시나리오 작성:

여러 Holo3 요청을 연결해 복잡한 멀티스텝 작업 루프를 시뮬레이션, 실제 배포 전에 시퀀스의 일관성과 안정성을 검증하세요.

Holo3 vs Claude Computer Use vs OpenAI Operator 비교

	Holo3-122B	Holo3-35B	Claude Computer Use	OpenAI Operator
OSWorld-Verified	78.85%	~55% (예상)	~65%	~62%
API 접근	예	예 (무료 등급)	예	예
공개 가중치	아니요	예 (Apache 2.0)	아니요	아니요
자체 호스팅	아니요	예	아니요	아니요
GPT-5.4 대비 비용	더 낮음	훨씬 낮음	비슷함	GPT-5.4 가격
적합 용도	프로덕션 엔터프라이즈	개발/테스트/오픈소스	Anthropic 생태계	OpenAI 생태계

실무 선택 팁:

Holo3-122B: 복잡 다중 앱 워크플로우, 높은 신뢰성/정확성 필요 시
Holo3-35B: 개발·테스트·오픈소스·자체 호스팅 필요 시
Claude Computer Use: Anthropic API 중심 스택
OpenAI Operator: GPT-5.4 및 OpenAI 단일 공급망 선호 시

엔터프라이즈 사용 사례

Holo3는 API 기반 자동화가 불가한 워크플로우도 지원합니다.

레거시 시스템 데이터 입력: REST API 없는 2000년대 ERP/CRM UI에 데이터 입출력 자동화
교차 플랫폼 조정: PDF→스프레드시트→대시보드 등 복수 앱 시퀀스 자동화
웹앱 회귀 테스트: 취약한 셀레늄 스크립트 대신 Holo3로 자연어 기반 테스트 자동화
경쟁 정보 분석: 스크래핑 방지 웹사이트에서 구조적 데이터 추출

H Company 벤치마크에 따르면, Holo3는 전자상거래/비즈니스/협업/다중 앱 등 다양한 엔터프라이즈 시나리오에서 강력한 성능을 보입니다. 특히 다중 앱 워크플로우에서 경쟁 대비 확실한 우위를 입증했습니다.

다음 단계: 적응형 에이전시

H Company는 적응형 에이전시(Adaptive Agency)라는 차세대 방향성을 명확히 제시하고 있습니다. 이는 기존에 본 적 없는 맞춤형 엔터프라이즈 소프트웨어를 실시간으로 탐색·학습해 작업을 수행하는 모델입니다.

현재의 모델들은 제한된 환경에서만 훈련되어, 미지의 내부 툴에서는 성공률이 낮습니다. 적응형 에이전시는 초회 접촉 시 소프트웨어 구조를 추론하고, 사전 학습 없이 업무를 실행하는 것을 목표로 합니다.

이 단계가 구현된다면, 엔터프라이즈 컴퓨터 사용 AI의 마지막 한계가 제거될 것입니다.

결론

Holo3는 데스크톱 컴퓨터 사용 자동화에서 새로운 기준을 세웠습니다. OSWorld-Verified 78.85%라는 압도적 성능, 복잡한 다중 앱 루프에서의 안정성, 그리고 Holo3-35B-A3B의 무료·오픈소스 가중치 제공으로 개발자 접근성도 높아졌습니다.

통합 패턴은 단순합니다: 스크린샷 → POST 요청 → 액션 실행 → 반복. Apidog는 응답 검증, 목(mock) 데이터, 통합 테스트 시나리오 등 실제 배포 전 신뢰성을 높일 수 있는 모든 기능을 제공합니다.

데스크톱 GUI 자동화가 필요하다면, Apidog를 무료로 사용해보고 Holo3 연동을 사전에 검증해보세요.

자주 묻는 질문 (FAQ)

Holo3는 무엇인가요?

Holo3는 H Company의 컴퓨터 사용 AI 모델로, 스크린샷을 입력으로 받아 데스크톱 또는 브라우저에서 작업을 완료하기 위한 액션(클릭, 키 입력, 스크롤)을 반환합니다. OSWorld-Verified 벤치마크에서 78.85%를 기록하며, 해당 분야 최고 점수입니다.

Holo3는 오픈 소스인가요?

Holo3-35B-A3B는 Apache 2.0 라이선스로 HuggingFace에서 공개 가중치 제공, 자체 호스팅이 가능합니다. 122B 모델은 API 전용입니다. 두 모델 모두 API 무료 등급으로 사용 가능합니다.

OSWorld 벤치마크는 어떻게 작동하나요?

OSWorld는 AI가 실제 컴퓨터에서 웹 내비게이션, 파일 관리, 교차 앱 워크플로우 등 실제 작업을 수행하도록 테스트합니다. 성공 여부는 작업 후 시스템 상태로 검증하며, 단순 출력 평가가 아닙니다.

Holo3와 Claude Computer Use의 차이는?

Holo3-122B는 OSWorld-Verified에서 78.85%로 Claude Computer Use(약 65%) 대비 높으며, 작업당 비용도 더 저렴합니다. Anthropic API 기반 팀에는 Claude도 강력한 선택지입니다.

Holo3를 로컬에서 실행할 수 있나요?

네. Holo3-35B-A3B는 Apache 2.0 라이선스 가중치로 HuggingFace에서 다운로드 후 자체 호스팅이 가능합니다. 122B 모델은 API만 지원합니다.

컴퓨터 사용 API의 주요 활용 사례는?

레거시 시스템 자동화, 교차 앱 데이터 워크플로우, 일반 언어 기반 웹앱 회귀 테스트, 경쟁 정보 스크래핑 등 사람이 수동 처리하던 데스크톱 작업 대체가 가능합니다.

Holo3 API 통합 테스트 방법은?

Apidog에서 엔드포인트를 등록하고, 응답 어설션을 설정하고, 개발 중엔 API 목(mock) 기능을 활용하세요. 여러 요청을 시나리오로 연결해 실제 배포 전 통합 오류를 사전에 발견할 수 있습니다.

Holo3 로드맵의 "적응형 에이전시"란?

H Company는 미지의 엔터프라이즈 소프트웨어를 실시간 탐색·학습해, 사전 훈련 데이터 없이 UI 구조를 이해하고 작업을 실행하는 모델 개발에 집중하고 있습니다. 이는 맞춤형 엔터프라이즈 배포의 마지막 한계를 제거할 것입니다.

axios 1.14.1 공급망 공격: 지금 해야 할 일

Rihpig — Thu, 02 Apr 2026 08:46:44 +0000

요약

2026년 3월 30-31일, npm에서 axios 버전 1.14.1과 0.30.4가 악성 종속성으로 인해 침해당했으며, 이는 감염된 기기에 원격 접속 트로이 목마(RAT)를 설치합니다. 두 버전 모두 게시가 취소되었습니다. 안전한 버전은 1.14.0입니다. axios@1.14.1 또는 0.30.4를 설치했다면, 해당 기기를 침해당한 것으로 간주하고 모든 자격 증명을 즉시 교체하십시오.

Apidog를 지금 사용해보세요

axios란 무엇이며, 왜 중요한가요?

axios는 npm에서 매주 1억 회 다운로드되는 핵심 HTTP 클라이언트 라이브러리입니다. 프런트엔드 프레임워크, 백엔드 Node.js 서비스 그리고 다양한 기업 애플리케이션에서 사용됩니다. 이러한 근본적인 패키지가 침해되면 그 영향은 체인 전체로 확산됩니다.

2026년 3월 30일부터 31일까지 짧은 기간 동안, 단순히 npm install 명령을 실행한 개발자들은 자신도 모르는 사이 악성코드를 시스템에 설치했습니다.

이 사건은 가상의 위험이 아니라 실제로 발생한 공급망 공격입니다. 페이로드는 임의 명령 실행, 데이터 유출, 감염 기기에 상주할 수 있는 멀티스테이지 원격 접속 트로이 목마였습니다.

팀에서 axios를 사용하고, Apidog로 HTTP 클라이언트 통합을 설계/테스트하고 있다면, 다음 배포 전 반드시 아래 내용을 점검하세요.

공격 타임라인

2026년 3월 30일 23:59:12 UTC: nrwise@proton.me 계정이 plain-crypto-js@4.2.1 악성 패키지 게시. 18시간 전 게시된 4.2.0 버전은 정상.
2026년 3월 31일 00:05:41 UTC: Socket 자동화 시스템이 plain-crypto-js@4.2.1을 6분 만에 악성으로 플래그.
2026년 3월 31일 자정 직후: axios@1.14.1이 npm에 게시되며, 침해된 plain-crypto-js@4.2.1을 종속성으로 포함. 해당 릴리스는 공식 GitHub 태그에 없음.
2026년 3월 31일 오전: GitHub 이슈 #10604에서 침해 보고. 관리자는 공격자 접근 권한을 즉시 철회하지 못함(더 높은 npm 권한 때문).
2026년 3월 31일: axios@1.14.1 및 axios@0.30.4가 npm에서 게시 취소됨. 관리자는 토큰 철회, 게시 제어 강화 등 대응 시작.

공격 방식

공격자는 axios의 게시 워크플로우 허점(장기 지속 npm 토큰)을 악용하여, 정상 릴리스 프로세스 밖에서 악성 버전을 게시했습니다.

새 버전은 plain-crypto-js@4.2.1(정상처럼 보이는 암호화 유틸리티 타이포스쿼트)을 종속성으로 도입했습니다.
해당 패키지 내부에는 다단계 페이로드가 포함되어 있었습니다.

악성 페이로드 동작

설치 시 실행: npm 라이프사이클 스크립트로 보조 페이로드 드롭.
RAT 배포: 지속적인 백도어 오픈.
유출: 임의 셸 명령 실행, 환경 변수/비밀 읽기, 네트워크로 데이터 전송.

RAT는 재부팅 후에도 지속됩니다. npm 패키지 제거만으로는 해결되지 않으니 반드시 명시적인 검색/제거 조치가 필요합니다.

제가 영향을 받았나요?

다음 조건에 해당하면 영향을 받았을 수 있습니다.

2026년 3월 30일 23:59 UTC ~ 3월 31일 정오 UTC 사이에 npm install axios 또는 npm install 실행(axios가 package.json에 있을 때)
node_modules/axios/package.json에 1.14.1 또는 0.30.4 버전이 표시됨
package-lock.json 또는 yarn.lock에서 axios가 1.14.1 또는 0.30.4로 해결됨

즉시 확인 방법

# 설치된 버전 확인
npm list axios

# 잠금 파일에서 axios 버전 찾기
grep '"axios"' package-lock.json | head -5

# plain-crypto-js 존재 여부 확인
npm list plain-crypto-js
ls node_modules/plain-crypto-js 2>/dev/null && echo "INFECTED" || echo "Not found"

plain-crypto-js가 node_modules에 존재하면, 악성 버전을 실제로 실행한 것입니다.

지금 해야 할 일

1. axios를 즉시 안전 버전으로 업데이트

npm install axios@1.14.0
# 또는 최신 안전 버전으로 고정
npm install axios@latest

확인:

npm list axios
# 1.14.0 이상(혹은 1.14.x의 클린 릴리스)이 표시되어야 합니다

2. 침해된 버전을 설치했다면

단순 업데이트가 아니라, 해당 기기가 침해된 것으로 간주하고 아래 조치를 수행하세요.

그 기기에서 접근 가능한 모든 비밀을 즉시 교체: API 키, DB 자격 증명, SSH 키, 클라우드 토큰, .env 변수 등
환경 변수 내 민감 정보 노출 여부 확인
영향받은 기간 내 아웃바운드 네트워크 연결 감사(알 수 없는 IP 연결 탐지)
지속성 체크: cron 작업, 시작 스크립트, systemd 서비스 등 감염 시점에 추가/수정된 항목 확인
침해된 버전이 설치된 서버/CI 러너라면 재이미징, 노트북은 자격 증명 전면 교체

3. CI/CD 파이프라인 감사

해당 기간 npm install을 실행한 빌드 파이프라인이 있다면, CI 환경도 침해되었을 수 있습니다.

# 빌드 로그에서 axios@1.14.1 설치 내역 확인

# CI 환경의 node_modules 점검
npm list axios plain-crypto-js

CI 파이프라인에서 접근 가능한 모든 비밀(배포 키, 클라우드 자격 증명, 레지스트리 토큰 등)도 교체하세요.

4. 잠금 파일(package-lock.json, yarn.lock) 확인 및 재생성

잠금 파일에 1.14.1이 존재한다면 반드시 재생성해야 합니다.

# 잠금 파일 제거 후 재설치
rm package-lock.json
npm install

새 잠금 파일이 안전한 버전으로 axios를 해결하는지 반드시 커밋 전에 확인하세요.

Apidog를 사용하여 axios API 호출 감사

API 호출에 axios를 사용한다면, Apidog는 종속성 업데이트 후에도 API 요청이 정상 동작하는지 빠르게 확인할 수 있습니다.

axios@1.14.0 이상으로 업데이트 후, Apidog로 기존 API 엔드포인트를 가져와 회귀 테스트를 실행하세요.
악성 버전이 요청/응답 페이로드를 변조했을 가능성도 있으므로, Apidog의 어설션 기능을 적극 활용하세요.

// Apidog 응답 후 어설션 예시
pm.test("응답이 깨끗합니다 — 주입된 필드가 없습니다", () => {
    const body = pm.response.json();
    pm.expect(body).to.not.have.property('__injected');
    pm.expect(pm.response.headers.get('X-Injected-Header')).to.be.null;
});

Apidog에서 전체 테스트 스위트를 실행하면, 프로덕션 배포 전 HTTP 클라이언트 동작에 대한 신뢰성 기준선을 확보할 수 있습니다.

Apidog 무료 체험으로 HTTP 클라이언트 회귀 테스트를 바로 시작하세요.

npm의 공급망 공격을 막기 어려운 이유

axios 공격은 예외가 아닙니다. 아래는 주목할 만한 npm 또는 OSS 공급망 공격 사례입니다.

event-stream (2018): 악성 관리자가 비트코인 지갑을 노린 페이로드 주입 (주간 800만 다운로드)
ua-parser-js (2021): 암호화폐 채굴기/비밀번호 탈취기 포함
node-ipc (2022): 특정 국가 대상 파괴적 코드 추가
xz utils (2024): Linux 핵심 압축 라이브러리에 백도어 심기
axios (2026): 관리자 자격 증명 침해 + 악성 종속성(RAT) 배포

공통점: 코드가 아닌 게시 계정에 대한 신뢰

npm의 구조상, 관리자 계정이 침해되면 공격자는 동일한 신뢰/권한을 이어받아 악성 패키지를 게시할 수 있습니다.

실제로 도움이 되는 공급망 보안 조치

조치	내용
잠금 파일(`package-lock.json`)	정확한 버전 고정, 자동 업데이트 방지
CI의 `npm audit`	배포 전 알려진 취약점 감지
Socket.dev / Snyk	행동 분석으로 CVE 등록 전에도 이상 탐지
npm 2단계 인증	계정 침해 난이도 상승
단기 토큰으로 `npm publish`	토큰 유출 시 노출 기간 최소화
PR에서 잠금 파일 검토	예기치 못한 종속성 변경 감지

axios 팀도 장기 토큰 문제를 인지하고, 더 엄격한 게시 제어로 전환 중입니다. 하지만 공급망 보안은 생태계 전체의 노력이 필요합니다.

침해 지표 (IOCs)

Socket 분석 기준:

악성 패키지: plain-crypto-js@4.2.1, axios@1.14.1, axios@0.30.4
게시자 이메일: nrwise@proton.me
행동: npm 설치 시 네트워크 연결, RAT 지속성, 환경 변수/비밀 유출
안전한 axios 버전: 1.14.0 이하(0.30.4 제외), 1.13.x, 1.12.x

감염 의심 시 security@npmjs.com으로 신고하고, 로그를 보존하세요.

결론

axios 1.14.1 침해 사건은 종속성 보안이 일회성 점검이 아니라 지속적이고 자동화된 프로세스이어야 함을 보여줍니다.

버전을 잠그고
CI에서 Socket과 같은 행동 분석 도구를 실행하며
이상 징후 발견 시 즉시 자격 증명 교체
PR/코드 리뷰에서 잠금 파일을 꼼꼼히 살펴보세요

axios 업데이트 후 API 통합 신뢰를 재구축하려면, Apidog는 배포 전 HTTP 클라이언트 동작을 검증할 수 있는 테스트 시나리오, 어설션, 목킹 도구를 제공합니다.

FAQ

어떤 axios 버전이 침해되었나요?

axios@1.14.1, axios@0.30.4입니다. 두 버전 모두 npm에서 게시가 취소되었습니다. 안전한 버전은 1.14.0(또는 1.13.x, 1.12.x 라인의 모든 버전)입니다.

악성 axios 페이로드는 무엇을 하나요?

plain-crypto-js@4.2.1을 가져와, 원격 접속 트로이 목마(RAT)를 포함한 다단계 페이로드를 배포합니다. RAT는 임의 명령 실행, 환경 변수 및 비밀 유출, 재부팅 후 지속 등이 가능합니다.

침해된 버전을 설치했는지 어떻게 알 수 있나요?

npm list axios 실행 시 1.14.1 또는 0.30.4가 표시되면 영향을 받은 것입니다. 또한 npm list plain-crypto-js로 plain-crypto-js가 존재하는지 확인하세요.

axios만 업데이트하면 충분한가요?

아닙니다. 업데이트는 향후 악성 종속성 설치를 막지만, RAT가 이미 기기에 설치되어 있을 수 있습니다. 침해된 버전을 설치했다면 모든 비밀을 교체하고, 기기에서 지속성(백도어) 여부를 반드시 점검하세요.

공격자는 어떻게 관리자가 아니면서 npm에 게시할 수 있었나요?

공격자는 관리자 자격 증명을 침해, 게시 권한이 있는 장기 npm 토큰을 악용한 것으로 보입니다. axios 팀은 게시 제어 강화를 진행 중입니다.

이것과 일반적인 취약점의 차이는 무엇인가요?

취약점은 정상 코드 내 결함입니다. 공급망 공격은 신뢰받는 게시 채널을 통해 악성 코드를 주입합니다. 침해된 코드는 axios GitHub 저장소에는 존재하지 않고, npm 게시에 직접 주입되었습니다.

향후 공급망 공격으로부터 프로젝트를 어떻게 보호할 수 있나요?

잠금 파일 사용, CI에서 npm audit 실행, Socket.dev 등 행동 분석 도구 추가, npm 2단계 인증 활성화, 단기 게시 토큰 사용, PR에서 잠금 파일 변경사항 감사 등 보안 수칙을 철저히 준수하세요.

2026년 최고의 AI 코딩 에이전트? 클로드 코드 vs 오픈클로

Rihpig — Thu, 02 Apr 2026 08:16:34 +0000

TL;DR / 빠른 답변

Claude Code는 터미널 및 IDE에서 코드 편집, 저장소 인식 추론, 자동 리뷰, 제어된 코딩 루프 등 집중적인 소프트웨어 엔지니어링 워크플로우에 적합합니다. OpenClaw는 다중 채널 메시징, 다중 공급자 라우팅, 플러그인 생태계, 게이트웨이 수준 자동화 등 광범위한 에이전트 작업에 더 강력합니다.

💡 API 팀에 실용적인 스택은 "Claude Code vs OpenClaw" 단일 선택이 아닙니다. 코딩 및 오케스트레이션에 적합한 도구를 사용한 후, Apidog로 API 수명주기를 설계, 테스트, 디버깅, 목킹, 문서화까지 일원화하세요.

지금 Apidog를 사용해보세요

소개

대부분의 "Claude Code vs OpenClaw" 비교글은 한 문장 요약으로 끝나지만, 이는 실제 도구 선택에 부족합니다.

엔지니어링 팀은 각 도구의 스택 내 역할, 운영 부담, 보안 제어, 실제 사용자 피드백까지 실질적인 정보를 필요로 합니다.

이 글에서는 다음을 실전 관점에서 비교합니다:

제품 범위 및 아키텍처
CLI/자동화 인터페이스
권한/승인/샌드박싱
메모리·컨텍스트 모델
통합/채널 지원 범위
다중 에이전트 운영 제어
커뮤니티 사용 사례

또한, 코딩 에이전트와 API 수명주기 도구가 분리될 때 Apidog의 핵심 역할도 명확히 설명합니다.

Apidog를 초기에 언급하는 이유: 코딩 에이전트만으로 API 전체 품질을 담보할 수 없습니다. 스키마 우선 설계, 회귀 테스트, 목킹, 문서화 등 실무 API 품질은 Apidog 같은 일원화된 시스템이 필요합니다.

주요 섹션 1: 핵심 제품 차이점

Claude Code와 OpenClaw는 일부 영역이 겹치지만, 완전한 대체재는 아닙니다.

Claude Code: 코드베이스 이해, 파일 편집, 명령 실행, IDE 연동, 세션·CI 워크플로우 등 개발자 코드 루프에 최적화된 에이전트.
OpenClaw: 모델 공급자, 채널 커넥터, 플러그인, 다중 에이전트 라우팅/운영자 제어 등, 게이트웨이 스타일 에이전트 플랫폼.

일상 업무에서의 의미

Claude Code: 개발자 루프(코드/저장소) 최적화
OpenClaw: 에이전트 플랫폼(운영/채널) 루프 최적화
저장소/PR 중심 팀 → Claude Code 적합
다중 채널/공급자/게이트웨이 제어 필요 → OpenClaw 적합

빠른 포지셔닝 표

범주	Claude Code	OpenClaw
주요 방향성	코딩 에이전트	에이전트 플랫폼 + 게이트웨이
주요 가치	개발자 워크플로우 품질	통합 및 오케스트레이션 범위
인터페이스 우선순위	터미널 + IDE	CLI + 채널 + 플러그인
초기 채택자	백엔드/플랫폼 개발팀	자동화 중심 운영팀
API 수명주기 범위	부분적(코딩)	부분적(자동화)

주요 섹션 2: 기능별 전체 비교

1) CLI 및 명령 모델

Claude Code: 대화/비대화, 세션, 시스템 프롬프트, 모델 설정, 워크트리/도구 제한 등 코딩 중심 CLI
OpenClaw: 에이전트, 모델, 메모리, 승인, 샌드박스, 브라우저, 크론, 웹훅, 채널, 플러그인, 시크릿, 보안 등 운영 전체 CLI

실전 팁: 코딩 업무에 특화된 CLI는 Claude Code, 다중 운영/통합 필요시 OpenClaw 선택

2) IDE 통합 및 코딩 UX

Claude Code: VS Code 확장, 인라인 diff, 진단, 컨텍스트, IDE 도구 통합 등
OpenClaw: 코딩 지원은 있으나, IDE 중심보다는 교차 채널/플랫폼 기능 중심

실전 팁: IDE 네이티브 개발 루프 → Claude Code, 시스템 간 워크플로우 → OpenClaw

3) 다중 에이전트 및 위임

Claude Code: 하위 에이전트/에이전트 팀 병렬 지원
OpenClaw: 다중 에이전트 라우팅, 별도 워크스페이스/정책 경계 명확

실전 팁: 단순 병렬 코딩 → Claude Code, 복잡한 에이전트 분할·운영 → OpenClaw

4) 메모리 및 장기 컨텍스트

Claude Code: CLAUDE.md 및 자동 프로젝트 메모리
OpenClaw: 시맨틱 검색, 파일 색인/검색 명령 등

실전 팁: 세션 내장형 메모리 → Claude Code, 명시적 운영 메모리 → OpenClaw

5) 보안 제어: 권한, 승인, 샌드박싱

Claude Code: 권한 설정, hook 기반 정책, 도구 액세스 제어
OpenClaw: 배포/신뢰 경계, 승인 정책, 게이트웨이 보안 강화

실전 팁: 코딩 정책 거버넌스 → Claude Code, 운영/채널 보안 강화 → OpenClaw

6) 훅(Hooks) 및 결정적 안전 장치

Claude Code: 도구 이벤트 기반 결정적 훅
OpenClaw: 게이트웨이/플러그인/운영 명령 기반 이벤트 자동화

실전 팁: 코드 표준/명령 안전 → Claude Code, 운영 자동화/통합 → OpenClaw

7) 모델 공급자 유연성

Claude Code: Claude 우선, 일부 외부 인프라 지원
OpenClaw: 다수 모델 공급자 카탈로그, 빠른 전환 지원

실전 팁: Claude만 → Claude Code, 다양한 공급자 혼합 → OpenClaw

8) 채널 및 메시징 통합

Claude Code: 협업 지원은 있으나 핵심 기능 아님
OpenClaw: Telegram, Slack, Discord, WhatsApp, Teams 등 다채널 공식 지원

실전 팁: 채널 중심 자동화 → OpenClaw

9) 플러그인 및 확장성

Claude Code: MCP, 명령, 훅 기반 코딩 확장성
OpenClaw: 플러그인 수명주기 관리, 마켓플레이스 패턴

실전 팁: 단일 개발자 확장 → Claude Code, 플랫폼 빌더 확장 → OpenClaw

10) 운영 오버헤드

Claude Code: 소프트웨어 팀 온보딩 빠름
OpenClaw: 게이트웨이 정책, 채널 보안, 운영 성숙도 필요

실전 팁: 빠른 코딩 전용 → Claude Code, 대규모 오케스트레이션 → OpenClaw

주요 섹션 3: 커뮤니티 사용 사례 (현장 신호)

체크리스트보다 실제 커뮤니티 신호가 중요합니다.

A. 로컬 머신 액세스 범위

Claude Code: 로컬 실행 강점. 단, 지침 범위(디렉터리/작업 경계) 설계가 중요.
넓은 권한보다 제한적 작업이 안전. 거버넌스 패턴 필수.

B. 세션 제한 압력 및 작업 스케줄링

Claude Code: 토큰 소모 많은 작업은 처리량 계획 필수.
배치/비피크 스케줄링 등 운영 패턴이 실제 팀 정책에 포함됨.

C. OpenClaw + Telegram 로컬 배포

OpenClaw: 원격 채널 기반 워크플로우에서 보안 강화 후 성공적 배포 사례.
터미널 외 채널/보안 설계가 중요 도입 관문.

D. 코딩 워커 포함 OpenClaw 오케스트레이션

OpenClaw: 다중 에이전트 파이프라인의 제어 평면 역할.
Claude Code: 코딩 전문 에이전트로 파이프라인 내 활용.

E. 채널 우선 자동화 실험

OpenClaw: 로봇 운영 등 채널 네이티브 자동화에서 강력한 실험 속도.
범용 코딩 에이전트 범위를 넘어서는 활용.

사회적 신호 요약

Claude Code: 저장소/IDE 중심 엔지니어링에 최적.
OpenClaw: 인터페이스/채널/에이전트 오케스트레이션에 최적.

주요 섹션 4: 온보딩 비용 및 온보딩 시간

단순 기능 비교가 아니라, 실제 도구 가격과 설정 부담도 평가해야 합니다.

온보딩 비용 스냅샷 (2026년 3월 27일 기준)

항목	Claude Code	OpenClaw
기본 제품 액세스	Anthropic 플랜 포함(월 $20~$100) 또는 API 종량제	MIT 오픈소스(플랫폼 라이선스 무료)
직접 라이선스	구독 플랜 필요	$0
사용 비용	Claude 제한·API 토큰	모델 API 사용량+인프라
예산 계획	좌석/토큰 예산	인프라+공급자-토큰 예산

온보딩 시간 스냅샷

단계	Claude Code	OpenClaw
첫 설치	빠름(Node+CLI 인증)	빠름(설치+`openclaw onboard`)
첫 사용	터미널/IDE 코딩 빠름	대시보드 채팅 빠름, 채널 연결 추가 시간
프로덕션 거버넌스	중간	중간~높음
최대 설정 위험	정책·권한 드리프트	게이트웨이/채널 보안 경계

실용적 해석

Anthropic 예산 있다면 Claude Code가 예측 가능.
OpenClaw는 소프트웨어 자체는 무료지만, 총 비용은 공급자/인프라/운영에 따라 달라짐.
코딩 전용 워크플로우라면 Claude Code가 빠름.
OpenClaw는 채널/보안 요구에 따라 온보딩 시간 증감.

주요 섹션 5: Apidog가 적합한 위치 (API 팀에게는 필수적)

Claude Code와 OpenClaw는 API 수명주기 거버넌스를 대체할 수 없습니다.

이 둘은 코드 생성/자동화에 특화되어 있지만, API 설계 계약, 회귀 테스트, 목킹 환경, 프로덕션 문서화는 Apidog 같은 API 플랫폼이 필수적입니다.

권장 아키텍처

Claude Code 또는 OpenClaw로 서비스 구현/리팩토링
API 정의/스키마는 Apidog에 관리
Apidog에서 엔드포인트 회귀·검증 시나리오 실행
Apidog로 API 문서 게시/관리
Apidog 환경/목킹 기능으로 프론트엔드/QA 병렬 작업 지원

예시: 에이전트 + Apidog 검증 루프

# 코딩 에이전트로 service 코드 생성/개선
npm run dev

# Apidog에서:
# 1) OpenAPI/컬렉션 임포트
# 2) 환경 및 인증 변수 설정
# 3) 성공/실패 시나리오 어서션 작성
# 4) 회귀 스위트로 저장

회귀 시나리오용 예시 페이로드

{
 "request": {
   "method": "POST",
   "url": "/v1/invoices",
   "body": {
     "customerId": "cus_1001",
     "amount": 1499,
     "currency": "USD"
   }
 },
 "expect": {
   "status": 201,
   "json": {
     "id": "string",
     "customerId": "cus_1001",
     "currency": "USD",
     "amount": 1499
   }
 }
}

실전 팁: 에이전트+Apidog 조합이 단독 에이전트 루프보다 회귀 위험을 줄이고 품질을 보장합니다.

주요 섹션 6: 팀 프로필별 의사결정 프레임워크

다음 경우 Claude Code를 먼저 선택

병목이 코드베이스 개발자 속도일 때
터미널/IDE 중심 개발 팀
코딩 UX/정책 hook이 중요한 팀
광범위한 채널 에이전트 운영이 필요 없는 팀

다음 경우 OpenClaw를 먼저 선택

어시스턴트가 채팅 채널/운영 표면 전반에 걸쳐야 할 때
다중 모델 공급자 유연성이 초기부터 필요할 때
명확한 게이트웨이 운영/라우팅 제어 필요
더 높은 운영 복잡성 감당 가능

다음 경우 둘 다 사용

OpenClaw로 오케스트레이션/제어, Claude Code로 코딩 전문가 역할 분담
팀 내 거버넌스 경계 관리 역량 확보
도구-역할 혼란 없이 명확한 역할 분리

다음 경우 항상 Apidog와 함께

API 계약 신뢰성, 회귀 안전성, 문서 품질이 필요한 경우
백엔드/QA/프론트/문서 이해관계자들이 하나의 API 작업 공간 필요

주요 섹션 7: 30일 파일럿 계획 (권장)

측정 없이 의견만으로 선택하지 마세요. 아래 절차로 검증하세요.

PR 주기, 유출 API 결함, 회귀 테스트 통과율, 정책 위반 사고 등 지표 선정
대표 서비스 2개(예: 하나는 CRUD API, 하나는 통합 API) 선정
각 후보 도구에서 동일한 작업 팩 실행
두 도구 모두에서 Apidog로 API 검증 고정
운영 비용 비교
엔지니어링/보안 팀과 결과 검토

이렇게 하면 방어 가능하고 효과적인 도구 결정을 내릴 수 있습니다.

주요 섹션 8: 팀 유형별 구현 플레이북

도입에서 실제 배포로 전환할 때 아래 플레이북을 참고하세요.

플레이북 A: 스타트업 API 팀 (5~12명)

초반 60일은 코딩 에이전트 1개만 집중
코드 리뷰/명령 안전 정책 표준화
모든 API 계약/회귀 작업은 Apidog에 집중
주간 리드타임/롤백/API 테스트 통과율 지표 관리

이유: 자동화 이득과 품질 일관성, 프레임워크 확산 방지

플레이북 B: 중규모 다중 제품 팀

저장소 중심 팀: Claude Code, 채널 중심 운영팀: OpenClaw
모든 제품은 공유 Apidog 작업공간 분류
엔드포인트 변경시 Apidog 테스트 증거와 함께 변경 노트 게시 요구

이유: 팀별 최적화 + Apidog 품질 관리 계층 확보

플레이북 C: 플랫폼/DevEx 팀

채널/시스템 전반 에이전트 오케스트레이션: OpenClaw
코드베이스 작업/리팩토링: Claude Code 병행
신뢰 경계/승인 규칙 명확화
배포 전 Apidog로 API 동작 검사 강제

이유: 오케스트레이션-코딩 분리, 자동화 범위 혼란 최소화

결론

Claude Code와 OpenClaw는 각각 강점이 다릅니다.

Claude Code: 순수 코딩 실행에 최적
OpenClaw: 오케스트레이션/채널 통합에 최적
커뮤니티 사용 사례: 실제 현장에서 위 구분이 확인됨
API 품질: 둘 다 Apidog과 함께 사용할 때 이상적

목표가 API 품질/속도라면 코딩/오케스트레이션 계층은 팀에 맞게 선택, API 수명주기 관리는 항상 Apidog에서 표준화하세요.

자주 묻는 질문 (FAQ)

이것이 정말 일대일 직접 비교인가요?

아닙니다. 일부 기능은 겹치지만, Claude Code는 코딩 중심, OpenClaw는 오케스트레이션 중심입니다.

OpenClaw가 Claude Code를 완전히 대체할 수 있나요?

코딩 깊이에 따라 다릅니다. OpenClaw로 자동화는 가능하지만, 일상 코딩 루프에서는 Claude Code가 더 강력할 때가 많습니다.

Claude Code가 채널 기반 워크플로우에서 OpenClaw를 대체할 수 있나요?

채널 중심 운영이라면 OpenClaw가 더 자연스럽습니다. 채널 통합이 문서화된 주요 기능입니다.

기술 비교에 커뮤니티 신호를 포함하는 이유는?

공식 사례 이전에 실제 사용자의 현장 경험이 도구의 한계, 실패/성공 패턴을 더 빨리 보여주기 때문입니다.

Apidog가 두 도구 중 하나와 겹치나요?

Apidog는 둘 다 보완합니다. 코딩 에이전트와 경쟁하지 않고, API 수명주기·협업 품질을 책임집니다.

시작하는 가장 안전한 방법은?

스코프를 좁혀서 시작하세요: 제한된 범위, 명확한 승인, 감사 가능한 테스트 흐름, 그리고 Apidog 기반 API 검증까지 적용하는 것이 안전합니다.