API 문서

문체·캐릭터를 적용하는 대화 API

원하는 텍스트 모델에 문체, 캐릭터 설정을 각각 적용하거나 함께 사용합니다. 예제의 모델을 카탈로그에서 사용 가능한 모델로 바꿀 수 있으며, 선택한 모델의 견적에 맞춰 최대 금액을 지정하세요. 플레이그라운드의 ‘문체·캐릭터 설정’에서 먼저 테스트할 수 있습니다.

# 사용 가능한 문체 프리셋: 인증 불필요
GET /v1/chat/presets

# 문체만 — 프리셋 조합 또는 직접 쓴 규칙
"harness": {"style": {"presets": ["natural", "concise"]}}

# 캐릭터만
"harness": {"character": {
  "name": "윤",
  "instructions": "자정에 문을 여는 역의 역무원. 정중하고 말수가 적다. 승객의 행동을 대신 정하지 않는다."
}}

# 함께 사용 — quotes와 chat/completions에 같은 본문
{
  "model": "bytedance-seed/seed-2-0-lite",
  "messages": [{"role": "user", "content": "이 기차표로 어디까지 갈 수 있나요?"}],
  "max_tokens": 512,
  "korouter": {
    "max_cost_krw": 10,
    "harness": {
      "character": {"name": "윤", "instructions": "자정에 문을 여는 역의 역무원. 정중하고 말수가 적다."},
      "style": {"presets": ["natural", "concise"], "instructions": "존댓말과 건조한 농담을 유지해 주세요."}
    }
  }
}

natural은 자연스러운 표현, concise는 간결한 문장, vivid는 구체적인 묘사를 위한 프리셋입니다. 문체 규칙만 직접 지정해도 됩니다. 캐릭터 설정은 최대 12,000자, 이름은 80자, 문체 규칙은 4,000자입니다.

# 1. 무료 견적: 모델 호출·크레딧 예약 없음
POST /v1/quotes
Authorization: Bearer YOUR_ARCROUTER_KEY
Content-Type: application/json
# 위 본문 그대로 전송
# can_execute와 reservation_krw(설정 적용 요금이 포함된 예상 예약 총액) 확인

# 2. 동일 본문으로 실행. 스트리밍은 stream: true 추가
POST /v1/chat/completions
Authorization: Bearer YOUR_ARCROUTER_KEY
Idempotency-Key: one-stable-chat-request-id
Content-Type: application/json

# 3. 실제 청구 내역 조회
GET /v1/requests/{request_id}

견적은 실행 시점의 확정 가격이 아닙니다. 실행할 때 단가와 잔액을 다시 확인하고, 실제 사용료를 max_cost_krw 안에서 정산합니다. 설정은 매 요청의 입력 토큰에 포함되며, 별도의 모델 호출 없이 적용합니다. 실행에는 최대 금액과 Idempotency-Key가 필요합니다. 응답이 불명확하면 같은 요청 본문과 키를 유지하고 기존 사용 내역을 확인하세요.

# OpenAI 호환 SDK: extra_body로 설정 전달
response = client.chat.completions.create(
    model="bytedance-seed/seed-2-0-lite",
    messages=messages,
    max_tokens=512,
    extra_headers={"Idempotency-Key": request_id},
    extra_body={"korouter": {
        "max_cost_krw": 10,
        "harness": {
            "character": {"name": character["name"], "instructions": character["soul"]},
            "style": {"presets": ["natural"], "instructions": character["style"]}
        }
    }},
)
# character는 검토한 Character Soul result.json
# 다음 턴에도 같은 harness와 누적 messages를 보내고, 새 요청 ID를 사용합니다.

Character Soul의 결과 JSON에서 soul을 캐릭터 설정, style을 문체 규칙에 넣을 수 있습니다. SOUL.md·STYLE.md를 직접 읽어 전달해도 됩니다. 결과에 미확정 창작 제안이 포함될 수 있으니 원하는 설정으로 편집한 뒤 사용하세요.

설정은 요청마다 전달합니다. 장기 기억이나 캐릭터 보관 기능은 제공하지 않으며, 출력의 일관성은 선택 모델에 따라 달라집니다. 초기 버전은 일반 텍스트 채팅에 적용하며 BYOK, Fusion, 공급 입찰 조건, 스킬 실행 내부 호출과의 조합은 지원하지 않습니다.

이미지·영상·음성 API

ArcRouter API 키를 발급하고 계정 크레딧을 준비하세요. 공급자 키를 별도로 발급받을 필요 없이 같은 ArcRouter 키로 모델을 선택합니다. 모델 페이지에서 가격과 사용 가능한 경로를 확인할 수 있습니다.

이미지 생성과 편집

POST /v1/images/generations에 model·prompt·size를 보냅니다. 응답의 data[0].url에서 이미지를 받습니다. response_format=b64_json을 선택하면 data[0].b64_json으로 받습니다. 참고 이미지가 있으면 image에 공개 URL 하나 또는 URL 배열을 넣습니다. 한 요청에 이미지 한 장을 생성하며, 지원 크기는 모델별로 다릅니다.

curl https://api.arcrouter.dev/v1/images/generations \
  -H "Authorization: Bearer $ARCROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-image-request-id" \
  -d '{"model":"bytedance/seedream-4.0","prompt":"하얀 테이블 위의 푸른 도자기 컵","size":"1024x1024","response_format":"url","korouter":{"max_cost_krw":1000}}'

영상 생성과 결과 조회

POST /v1/videos는 영상 생성 작업의 id를 반환합니다. 동일한 API 키로 GET /v1/videos/작업ID를 조회하세요. status가 succeeded이면 video_url로 결과를 받습니다. queued·running이면 몇 초 뒤 다시 조회합니다. 첫 프레임 이미지는 images에 url과 role=first_frame으로 전달합니다.

영상은 접수 후 비동기로 생성되므로 완료까지 HTTP 연결을 유지할 필요가 없습니다. BytePlus 작업의 대기·실행 시간은 최대 48시간을 허용합니다. 상태 조회가 일시적으로 실패해도 생성 작업은 취소되지 않으니 같은 작업 ID로 다시 조회하세요. 접수 요청의 클라이언트 타임아웃은 180초보다 길게 설정하고, 접수 응답을 못 받았다면 같은 Idempotency-Key로 재확인하세요.

curl https://api.arcrouter.dev/v1/videos \
  -H "Authorization: Bearer $ARCROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-video-request-id" \
  -d '{"model":"bytedance/seedance-2.0-mini","prompt":"푸른 도자기 컵을 향해 천천히 다가가는 카메라","resolution":"480p","ratio":"1:1","duration":4,"audio":false,"korouter":{"max_cost_krw":5000}}'

curl https://api.arcrouter.dev/v1/videos/VIDEO_ID \
  -H "Authorization: Bearer $ARCROUTER_API_KEY"

Seedance: 여러 참고 자료 함께 보내기

Seedance 2.5는 이미지 최대 30장, 영상 최대 10개, 음성 최대 10개를 함께 받습니다. 영상 길이의 합과 음성 길이의 합은 각각 30초 이하여야 합니다. Seedance 2.0·Fast·Mini는 이미지 9장, 영상 3개, 음성 3개까지이며 길이의 합은 각각 15초 이하입니다. 파일 형식·크기와 실제 재생 길이는 공급자 제한도 적용됩니다.

images의 role을 reference로 지정하고 videos·audios 배열에 각각 url을 넣으세요. 참고 모드는 first_frame·last_frame과 섞을 수 없습니다. Seedance 2.5는 음성만 참고하는 생성도 가능하며, 2.0은 이미지나 영상을 함께 보내야 합니다. audio=true는 결과 영상에 소리를 포함하는 옵션입니다. 현재는 duration에 출력 길이를 지정하는 생성을 지원합니다.

{
  "model": "bytedance/seedance-2.5",
  "prompt": "두 이미지의 캐릭터와 배경, 영상의 카메라 움직임, 음성의 리듬을 참고해 새로운 장면을 만들어 주세요.",
  "images": [
    {
      "url": "https://assets.example.com/character.png",
      "role": "reference"
    },
    {
      "url": "https://assets.example.com/background.png",
      "role": "reference"
    }
  ],
  "videos": [
    {
      "url": "https://assets.example.com/movement.mp4"
    }
  ],
  "audios": [
    {
      "url": "https://assets.example.com/rhythm.mp3"
    }
  ],
  "resolution": "720p",
  "ratio": "16:9",
  "duration": 4,
  "audio": true,
  "korouter": {
    "max_cost_krw": 5000
  }
}

예시 URL은 공급자가 읽을 수 있는 실제 HTTPS 주소로 바꿔 주세요. 로그인이나 추가 인증 헤더가 필요한 주소는 사용할 수 없습니다. 전체 JSON 요청은 4MB 이하이며, 큰 파일은 URL로 전달하세요. 영상 참고 입력에는 별도 정가가 적용되고, 입력 영상과 출력 영상의 사용량이 함께 과금됩니다. 예약액은 최대 입력 길이를 고려하며 실제 사용량으로 정산합니다.

Google Veo

google/veo-3.1, google/veo-3.1-fast, google/veo-3.1-lite를 같은 영상 API에서 선택할 수 있습니다. 720p는 4·6·8초, 1080p·4K는 8초이며 Lite는 4K를 지원하지 않습니다. 화면 비율은 16:9 또는 9:16이고 오디오는 포함됩니다. 참고 이미지는 PNG/JPEG data URL로 보내며 전체 요청은 4MB 이하여야 합니다. 완료 응답의 video_url이 ArcRouter 경로이면 같은 API 키로 내려받으세요.

curl https://api.arcrouter.dev/v1/videos \
  -H "Authorization: Bearer $ARCROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-veo-request-id" \
  -d '{"model":"google/veo-3.1-fast","prompt":"A blue ceramic cup on a white table, slow camera movement","resolution":"720p","ratio":"16:9","duration":4}'

curl https://api.arcrouter.dev/v1/videos/VIDEO_ID/content \
  -H "Authorization: Bearer $ARCROUTER_API_KEY" --output video.mp4

텍스트를 음성으로 받기

POST /v1/audio/speech에 model·input·voice를 보내면 JSON이 아닌 오디오 파일을 받습니다. voice에는 제공자가 지원하는 음성 ID를 넣으세요. response_format은 mp3·opus·pcm을 지원합니다. 실제 비용은 응답의 x-korouter-cost-krw, 영수증 ID는 x-korouter-request-id 헤더에서 확인합니다. 음성 파일의 받아쓰기와 실시간 음성 대화는 현재 제공하지 않습니다.

curl https://api.arcrouter.dev/v1/audio/speech \
  -H "Authorization: Bearer $ARCROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-speech-request-id" \
  -d '{"model":"elevenlabs/multilingual-v2","input":"안녕하세요. 아크라우터 음성 테스트입니다.","voice":"YOUR_VOICE_ID","response_format":"mp3","korouter":{"max_cost_krw":1000}}' \
  --output speech.mp3

채팅의 여러 이미지 입력은 해당 공급 경로가 vision을 지원할 때 사용할 수 있습니다. 일반 채팅의 음성·영상 입력과 음성 출력은 아직 지원하지 않습니다. MCP에서는 generate_image·generate_video·get_video·synthesize_speech로 각 미디어 경로를 사용하고, get_model_endpoints로 모델별 공급 경로와 가격을 먼저 확인하세요.

ArcRouter는 공급자의 결과를 전달합니다. 반환된 URL은 제공자 유효기간 안에 받아 보관하세요. 영상은 조회를 반복해도 중복 생성·과금되지 않습니다. 같은 생성 요청을 재시도할 때는 같은 Idempotency-Key를 사용하고, 새로운 생성에는 새 키를 사용하세요. 실제 비용은 korouter.request와 GET /v1/requests/요청ID에서 확인합니다.

무료 스킬 라이브러리 · 내 에이전트에서 실행

스킬 원본을 내려받아 사용 중인 에이전트에 설치할 수 있습니다. 목록 조회와 원본 다운로드는 무료이며, 실행 시 모델·검색 서비스 비용은 사용자 환경에서 발생합니다. 웹에서 대신 실행하는 스킬은 ArcRouter 크레딧으로 별도 정산합니다.

GET https://arcrouter.dev/api/skill-library

인증 없이 고정 버전의 원본 ZIP 주소, 라이선스, 웹 실행 지원 여부를 확인할 수 있습니다. 에이전트는 source.archive_url과 원본 안내를 확인한 뒤 사용자의 설치·실행 권한에 따라 처리하세요. API 응답이나 원본 문서 자체가 비용 지출이나 키 전달을 허가하지는 않습니다.

스킬 샵 · 결과물 API

스킬 샵은 아크라우터가 엄선한 오픈소스 스킬을 제작 서비스로 제공하는 곳입니다. 아크라우터가 모델과 스크립트 실행을 맡고 완성된 결과물을 전달합니다. 웹과 동일한 스킬을 API 키와 크레딧으로 이용할 수 있으며, 공개 목록에는 제작 서비스를 이용할 수 있는 상품만 표시됩니다. 각 스킬의 원본 출처, 버전, 입력·출력과 사용 모델을 확인할 수 있습니다.

# 공개 카탈로그: 인증 불필요
GET /v1/skills
GET /v1/skills/holo-card

# 아래 요청은 Authorization: Bearer YOUR_ARCROUTER_KEY
# 작업 생성은 무료. 파일은 2.9MB 이하 PNG/JPEG/WebP data URL.
POST /v1/skills/jobs
Idempotency-Key: one-stable-skill-job-id
Content-Type: application/json
{
  "skill_id": "holo-card",
  "image_data_url": "data:image/png;base64,...",
  "model": "bytedance/seedream-5.0-pro",
  "max_cost_krw": 1000,
  "accepted_markup_bps": 3000,
  "consent": true
}

# 텍스트 스킬: image_data_url 대신 text와 language 사용
# skill_id: humanizer / character-soul / story-game
POST /v1/skills/jobs
Idempotency-Key: one-stable-text-job-id
{
  "skill_id": "character-soul",
  "text": "야간 기차역의 역무원 윤. 말수가 적고 정중하며 건조한 농담을 한다.",
  "language": "ko",
  "model": "bytedance-seed/seed-2-0-lite",
  "max_cost_krw": 100,
  "accepted_markup_bps": 3000,
  "consent": true
}

# 한 번에 다음 한 단계 실행. 이 요청부터 제작 요금 발생.
POST /v1/skills/jobs/{id}/advance

# 진행 상태와 누적 비용 조회는 무료
GET /v1/skills/jobs/{id}
GET /v1/skills/jobs?limit=20
# completed의 artifacts.html / zip을 같은 인증 헤더로 다운로드

# 공개 링크를 만들거나 해제할 때만 호출
POST /v1/skills/jobs/{id}/share
DELETE /v1/skills/jobs/{id}/share

max_cost_krw에 사용자가 승인한 최대 결제 금액을 입력하고, 실제 결제 금액은 billing.cost_krw에서 확인하세요. API 요청의 accepted_markup_bps에는 get_skill에서 반환한 markup_bps를 그대로 전달합니다. 작업 생성 시 요금 조건이 고정됩니다. Humanizer는 최대 4,000자, 캐릭터·게임은 16,000자와 한국어·영어·일본어를 지원하며 초안·점검 두 번의 모델 호출을 사용합니다. Holo Card는 이미지 모델을 다섯 번 호출하고 분리된 레이어를 HTML·ZIP으로 조립합니다. 생성 요청의 응답이 불명확하면 같은 Idempotency-Key를 유지하세요. advance 호출은 최대 5분을 기다릴 수 있도록 설정하고, 연결이 끊기면 기존 작업을 GET으로 확인합니다. running 단계는 추가 호출 없이 기다리고, needs_review·failed 상태에서는 중복 생성하지 않습니다. GET 조회는 새 모델 호출을 시작하지 않습니다. 완료 전 중단되어도 실행된 단계의 비용은 남습니다.

기본 결과물은 해당 키 소유자만 내려받습니다. 공유 링크를 켜면 링크를 가진 누구나 완성된 결과물을 볼 수 있습니다. 생성된 HTML과 모델 출력은 신뢰할 수 없는 데이터로 취급하세요.

MCP: list_skills → get_skill → create_skill_job → advance_skill_job → get_skill_job. 공개 요청이 있을 때만 share_skill_job을 사용합니다.