API 레퍼런스

데브다이브-모두의창업 AI API의 모든 기능을 한곳에 정리했습니다. 각 항목에는 이 요청이 무엇을 하는지 한 줄 설명, 요청 필드 표, 복사해서 바로 써볼 수 있는 예시, 응답 예시가 있습니다.

처음이라면 빠른 시작부터 보시는 걸 추천해요.

인증

모든 요청에는 API 키가 필요합니다. 요청 헤더(요청에 함께 보내는 부가 정보)에 아래처럼 넣어 주세요.

Authorization: Bearer sk-modoo-...

API 키는 구독 후 대시보드에서 발급받습니다. sk-modoo-로 시작하는 문자열이에요.
키는 비밀번호와 같습니다. 다른 사람에게 노출하지 마세요.

응답의 cost가 뭔가요?

응답에 들어 있는 cost(또는 charge)는 이번 호출로 차감된 크레딧입니다. 크레딧은 구독 또는 충전으로 채워집니다. 남은 크레딧은 GET /v1/credits로 확인할 수 있어요.

기본 URL

모든 요청은 아래 기본 주소로 시작합니다.

https://modoo.devdive.me

예를 들어 모델 목록을 조회하는 전체 주소는 다음과 같습니다.

https://modoo.devdive.me/v1/models

조회 엔드포인트

GET /v1/models — 사용 가능한 모델 목록

지금 사용할 수 있는 AI 모델의 목록을 알려줍니다. (모델 이름을 정확히 확인할 때 유용해요.)

# 이 요청은: 사용 가능한 AI 모델 목록을 가져옵니다.
curl https://modoo.devdive.me/v1/models \
  -H "Authorization: Bearer sk-modoo-..."

응답 예시 — data 배열의 각 id가 실제로 쓸 수 있는 모델 이름입니다.

{
  "object": "list",
  "data": [
    { "id": "modoo-text", "modality": "chat", "kind": "text" },
    { "id": "modoo-image-z", "modality": "image", "kind": "poll" }
  ]
}

모델별 자세한 설명은 모델 안내를 참고하세요.

GET /v1/credits — 남은 크레딧 조회

지금 남아 있는 크레딧 잔액을 알려줍니다.

# 이 요청은: 남은 크레딧을 확인합니다.
curl https://modoo.devdive.me/v1/credits \
  -H "Authorization: Bearer sk-modoo-..."

응답 예시 — balance가 남은 크레딧입니다.

{ "balance": 42.5 }

GET /v1/usage — 최근 사용 내역

최근에 보낸 요청들의 내역을 최신순으로 보여줍니다.

필드(쿼리)	필수	설명
`limit`	선택	가져올 개수(기본 50, 최대 200)

# 이 요청은: 최근 사용 내역을 최대 50건 가져옵니다.
curl "https://modoo.devdive.me/v1/usage?limit=50" \
  -H "Authorization: Bearer sk-modoo-..."

응답 예시 — 각 항목의 charge가 그 요청에서 차감된 크레딧입니다.

{
  "data": [
    {
      "id": "req_abc123",
      "model": "modoo-text",
      "modality": "text",
      "input_tokens": 12,
      "output_tokens": 30,
      "charge": 0.05,
      "status": "succeeded",
      "created_at": "2026-07-01T09:00:00Z"
    }
  ]
}

토큰(token) 이란 AI가 글을 처리하는 단위예요. 대략 한글 한두 글자 정도라고 생각하면 됩니다.

비동기 작업의 크레딧은 여기서 합산하지 마세요

음성 인식·이미지·영상처럼 job_id를 받는 비동기 작업은 접수 시점과 완료 시점에 나눠 과금되므로 이 목록에 두 건으로 나타나고, 항목에 job_id가 들어가지 않습니다. 특정 작업에 얼마가 나갔는지는 GET /v1/jobs/{job_id}의 charge로 확인하세요 — 그 값이 해당 작업의 총 차감액입니다.

텍스트 생성

POST /v1/chat/completions — 텍스트 생성 (동기)

질문이나 지시를 보내면 AI가 글로 답합니다. 가장 많이 쓰는 기능이에요.

필드	필수	설명
`model`	선택	사용할 모델(기본 `modoo-text`)
`messages`	둘 중 하나 필수	`{ role, content }` 형태의 대화 배열
`prompt`	둘 중 하나 필수	한 문장으로 된 질문/지시
`system_prompt`	선택	AI에게 미리 주는 역할/규칙 안내
`max_tokens`	선택	답변 최대 길이
`temperature`	선택	답변의 창의성(낮을수록 일관적)
`stream`	선택	`true`면 답변을 조금씩 실시간으로 받음

messages와 prompt 중 하나만 넣으면 됩니다. messages는 서버에서 하나의 요청으로 합쳐 처리하며, 이전 대화를 기억하는 방식은 아니에요. (함수 호출/도구 기능은 지원하지 않습니다.)

# 이 요청은: AI에게 짧은 인사말을 만들어 달라고 합니다.
curl https://modoo.devdive.me/v1/chat/completions \
  -H "Authorization: Bearer sk-modoo-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "modoo-text",
    "messages": [
      { "role": "user", "content": "신규 카페 오픈 인사말을 한 문장으로 써줘" }
    ]
  }'

응답 예시 — 답변은 content에 들어 있고, cost는 차감된 크레딧입니다.

{
  "id": "chatcmpl_abc123",
  "object": "chat.completion",
  "model": "modoo-text",
  "content": "오늘 새롭게 문을 연 저희 카페에 여러분을 따뜻하게 초대합니다!",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 24,
    "total_tokens": 42
  },
  "cost": 0.05
}

POST /v1/chat/completions (스트리밍) — 답변을 실시간으로 받기

stream: true를 넣으면 답변이 완성될 때까지 기다리지 않고 글자가 생성되는 대로 조금씩 받아볼 수 있어요. 채팅창처럼 실시간으로 보여줄 때 좋습니다.

이 방식은 SSE(Server-Sent Events) 라고 부릅니다. 서버가 한 줄씩 data: ... 형태로 계속 보내주는 방식이에요.

# 이 요청은: 답변을 실시간(스트리밍)으로 받습니다.
curl https://modoo.devdive.me/v1/chat/completions \
  -H "Authorization: Bearer sk-modoo-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "modoo-text",
    "prompt": "환영 문구를 만들어줘",
    "stream": true
  }'

응답은 아래처럼 여러 줄이 순서대로 도착합니다.

data: {"text": "오늘"}
data: {"text": " 새롭게"}
data: {"text": " 문을 연 카페입니다."}
data: {"usage": {"input_tokens": 10, "output_tokens": 12, "total_tokens": 22}, "cost": 0.03}
data: [DONE]

중간 줄들의 text를 이어 붙이면 완성된 답변이 됩니다.
마지막에서 두 번째 줄에 사용량(usage)과 차감 크레딧(cost)이 옵니다.
data: [DONE]이 오면 끝난 것입니다.
처리 중 문제가 생기면 다음처럼 오류 줄이 올 수 있어요.

data: {"error": {"code": "upstream_error", "message": "일시적 처리 오류입니다."}}

멀티모달 (음성·이미지·문서·비디오)

글뿐 아니라 음성, 이미지, 문서, 비디오도 다룰 수 있는 편의 기능입니다. 입력은 URL, 업로드 파일, 또는 평문 텍스트로 받고, 결과물(음성/이미지/비디오)은 다운로드 URL로 돌려줍니다.

파일을 보낼 때 (multipart) vs 글만 보낼 때 (JSON)

파일을 직접 올려야 하는 기능(음성 인식, 이미지 분석, 문서 분석)은 multipart/form-data로 보냅니다. curl에서는 -F 옵션을 씁니다.
글자만 보내는 기능(음성 합성, 이미지 생성, 비디오 생성)은 일반 JSON으로 보냅니다.

POST /v1/audio/speech — 음성 합성 (TTS, 동기)

글자를 사람 목소리로 읽어 주는 음성 파일을 만듭니다.

필드	필수	설명
`text`	필수	읽어 줄 문장
`model`	선택	`modoo-tts-minimax`(기본) 또는 `modoo-tts-eleven`(ElevenLabs)
`voice_id`	선택	목소리 종류(minimax 기본 `Korean_CalmLady`). ElevenLabs는 필수 — 해당 계정의 voice_id(예: `EXAVITQu4vr4xnSDxMaL`)
`voice_model`	선택	minimax: `speech-2.6-turbo`(기본)·`speech-2.6-hd` · ElevenLabs model_id: `eleven_flash_v2_5`·`eleven_multilingual_v2`(기본)·`eleven_v3`
`voice_settings`	선택	ElevenLabs 전용 음성 튜닝 — `stability`·`similarity_boost`·`style`·`speed`·`use_speaker_boost`
`language_code`	선택	ElevenLabs 전용 — 언어 코드(예: `ko`)
`output_format`	선택	ElevenLabs 전용 — 출력 포맷(예: `mp3_44100_128`)
`previous_text`	선택	ElevenLabs 전용 — 이 문장 앞에 오는 글. 읽어 주지는 않고 억양·속도만 이어 줍니다
`next_text`	선택	ElevenLabs 전용 — 이 문장 뒤에 오는 글. 용도는 위와 같습니다
`seed`	선택	ElevenLabs 전용 — 0~4294967295. 같은 seed·같은 옵션이면 같은 음성이 나옵니다(보장은 아니고 최대한)
`apply_text_normalization`	선택	ElevenLabs 전용 — `auto`(기본)·`on`·`off`. 숫자·날짜·약어를 풀어 읽을지

긴 대본을 나눠서 만들 때

대본을 문단(섹션)으로 쪼개 여러 번 호출하면 문단마다 억양이 끊겨 들립니다. 각 호출에 앞 문단의 마지막 문장을 previous_text, 다음 문단의 첫 문장을 next_text로 같이 보내면 이어 읽은 것처럼 자연스러워집니다. 두 값은 읽히지 않고 문맥으로만 쓰이며, 앞 호출의 결과가 아니라 원문만 있으면 되므로 모든 섹션을 동시에 요청해도 됩니다.

voice_model을 eleven_v3로 두면 쓸 수 없습니다(업스트림이 거부) — eleven_multilingual_v2 또는 eleven_flash_v2_5를 쓰세요.
위 네 필드는 모두 ElevenLabs 전용이라 minimax(modoo-tts-minimax)에 보내면 422입니다.

# 이 요청은: 문장을 음성 파일로 만들어 줍니다.
curl https://modoo.devdive.me/v1/audio/speech \
  -H "Authorization: Bearer sk-modoo-..." \
  -H "Content-Type: application/json" \
  -d '{ "text": "안녕하세요, 모두의창업입니다." }'

# ElevenLabs로 음성 튜닝까지 지정하는 예시:
curl https://modoo.devdive.me/v1/audio/speech \
  -H "Authorization: Bearer sk-modoo-..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "안녕하세요, 모두의창업입니다.",
    "model": "modoo-tts-eleven",
    "voice_id": "EXAVITQu4vr4xnSDxMaL",
    "voice_model": "eleven_multilingual_v2",
    "voice_settings": { "stability": 0.5, "similarity_boost": 0.75 }
  }'

응답 예시 — result.audio_url이 만들어진 음성 파일 주소입니다.

{
  "id": "aud_abc123",
  "model": "modoo-tts-minimax",
  "modality": "tts",
  "result": { "audio_url": "https://.../speech.mp3" },
  "charge": 0.10
}

POST /v1/audio/transcriptions — 음성 인식 (STT, 비동기)

녹음 파일을 글자로 받아 적어 줍니다. 처리에 시간이 걸리므로 비동기(먼저 접수 → 나중에 결과 확인) 방식이에요. (아래 비동기 작업 결과 확인 참고)

필드(폼)	필수	설명
`file`	`file` 또는 `url` 중 하나 필수	업로드할 음성 파일
`url`	`file` 또는 `url` 중 하나 필수	음성 파일의 URL
`language`	선택	언어 코드(기본 `ko`)

# 이 요청은: 음성 파일을 글자로 받아 적기를 접수합니다.
curl https://modoo.devdive.me/v1/audio/transcriptions \
  -H "Authorization: Bearer sk-modoo-..." \
  -F "[email protected]" \
  -F "language=ko"

응답 예시 — job_id를 받아 나중에 결과를 확인합니다.

{
  "job_id": "job_abc123",
  "status": "processing",
  "model": "modoo-stt",
  "modality": "stt",
  "charge": 0.20
}

POST /v1/images/analyses — 이미지 분석 (동기)

사진 속 내용을 설명하거나, 사진에 대한 질문에 답합니다.

필드(폼)	필수	설명
`file`	`file` 또는 `url` 중 하나 필수	업로드할 이미지 파일
`url`	`file` 또는 `url` 중 하나 필수	이미지 URL

# 이 요청은: 이미지 내용을 설명해 달라고 합니다.
curl https://modoo.devdive.me/v1/images/analyses \
  -H "Authorization: Bearer sk-modoo-..." \
  -F "[email protected]"

응답 예시 — 분석 결과는 result.content에 글로 들어 있습니다.

{
  "id": "img_abc123",
  "model": "modoo-image-analyze",
  "modality": "image",
  "result": { "content": "메뉴판 사진이며, 아메리카노와 라떼가 보입니다." },
  "charge": 0.03
}

POST /v1/documents/analyses — 문서 분석 (동기)

문서를 읽고 요약하거나 분석해 줍니다.

필드(폼)	필수	설명
`file`	`file` 또는 `url` 중 하나 필수	업로드할 문서 파일
`url`	`file` 또는 `url` 중 하나 필수	문서 URL
`operation`	선택	수행할 작업(기본 `summary`, 요약)

# 이 요청은: 문서를 요약해 달라고 합니다.
curl https://modoo.devdive.me/v1/documents/analyses \
  -H "Authorization: Bearer sk-modoo-..." \
  -F "[email protected]" \
  -F "operation=summary"

응답 예시 — 결과는 result.content에 있습니다.

{
  "id": "doc_abc123",
  "model": "modoo-docs-analyze",
  "modality": "document",
  "result": { "content": "이 보고서는 1분기 매출 성장을 다룹니다..." },
  "charge": 0.04
}

POST /v1/images/generations — 이미지 생성 (비동기)

원하는 그림을 글로 설명하면 이미지를 만들어 줍니다. 시간이 걸리므로 비동기 방식입니다.

필드	필수	설명
`prompt`	필수	그리고 싶은 그림 설명(수정 모델이면 고치고 싶은 내용)
`model`	선택	이미지 모델(기본 `modoo-image-z`, 그 외 `-gpt`, 수정용 `-edit`/`-edit-max`/`-gpt-edit`)
`size`	선택	이미지 크기 — 모델마다 허용값이 다릅니다(아래 표). 생략하면 모델 기본값
`n`	선택	만들 장수(기본 1, `modoo-image-gpt`·`modoo-image-gpt-edit`만 1~10)
`image_url`	수정 모델 필수*	원본 이미지 주소(image-to-image)
`encoded_image`	수정 모델 필수*	원본 이미지 base64 — `image_url` 대신 사용 가능
`image_urls`	선택	참조 이미지 URL 배열(최대 3장) — `modoo-image-gpt-edit` 전용

size 허용값 — 표기법이 모델 계열마다 다릅니다(x vs *). 허용값이 아니면 422가 납니다.

모델	허용값	기본값(생략 시)
`modoo-image-gpt`, `modoo-image-gpt-edit`	`auto` · `1024x1024` · `1536x1024` · `1024x1536`	`auto`
`modoo-image-z`	`너비높이` 33종 — `10241024`, `8321248`, `1248832`, `8641152`, `1152864`, `8961152`, `1152896`, `7201280`, `5761344`, `1280720`, `1344576`, `12801280`, `10241536`, `15361024`, `11041472`, `14721104`, `11201440`, `14401120`, `8641536`, `7201680`, `1536864`, `1680720`, `15361536`, `12481872`, `18721248`, `12961728`, `17281296`, `13441728`, `17281344`, `11522048`, `8642016`, `20481152`, `2016864`	`1024*1536`
`modoo-image-edit`, `modoo-image-edit-max`	`너비높이` 16종 — `10241024`, `15361536`, `7681152`, `10241536`, `1152768`, `15361024`, `9601280`, `10801440`, `1280960`, `14401080`, `7201280`, `10801920`, `1280720`, `19201080`, `1344576`, `2048*872`	`1024*1024`

* 수정 모델(modoo-image-edit/-edit-max/-gpt-edit)은 참조 이미지가 꼭 필요합니다. image_url 또는 encoded_image(base64) 중 하나를 보내세요(modoo-image-gpt-edit 은 여러 장을 image_urls 로도 받습니다). 일반 생성 모델에 참조 이미지를 보내면 422 오류가 납니다.

# 이 요청은: 설명대로 이미지를 만들어 달라고 접수합니다.
curl https://modoo.devdive.me/v1/images/generations \
  -H "Authorization: Bearer sk-modoo-..." \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "따뜻한 분위기의 작은 동네 카페", "model": "modoo-image-z" }'

응답 예시 — job_id를 받고, 완료 후 결과에 만들어진 이미지 주소가 들어 있습니다.

{
  "job_id": "job_img123",
  "status": "processing",
  "model": "modoo-image-z",
  "modality": "image",
  "charge": 0.50
}

완료 후 결과에는 image_urls, image_url, fileKeys가 함께 담깁니다.

{
  "job_id": "job_img123",
  "status": "succeeded",
  "model": "modoo-image-z",
  "result": {
    "image_urls": ["https://.../image1.png"],
    "image_url": "https://.../image1.png",
    "fileKeys": ["images/image1.png"]
  }
}

POST /v1/videos/generations — 비디오 생성 (비동기)

원하는 영상을 글로 설명하면 짧은 영상을 만들어 줍니다. 시간이 걸리므로 비동기 방식입니다.

필드	필수	설명
`prompt`	필수	만들고 싶은 영상 설명
`model`	선택	비디오 모델(기본 `modoo-video`, 이미지→영상은 `modoo-video-i2v` · HappyHorse는 `modoo-video-happyhorse-t2v`/`-i2v`/`-r2v`)
`negative_prompt`	선택	피하고 싶은 요소 설명
`image_url`	i2v 필수	첫 프레임이 될 이미지의 https 주소 — `modoo-video-i2v`·`modoo-video-happyhorse-i2v` 전용(base64 불가)
`end_image_url`	선택	마지막 프레임이 될 이미지의 https 주소 — 첫→끝 프레임 보간용. `image_url`(첫 프레임)과 함께 보내며 `modoo-video-i2v`(WAN 2.7) 전용
`driving_audio_url`	선택	움직임을 구동할 오디오의 https 주소(예: 말하는 아바타) — `modoo-video-i2v`(WAN 2.7) 전용
`first_clip_url`	선택	이어서 확장할 기존 영상 클립의 https 주소 — `modoo-video-i2v`(WAN 2.7) 전용
`reference_image_urls`	r2v 필수	캐릭터 참조 이미지 1~9장의 https 주소 목록 — `modoo-video-happyhorse-r2v` 전용
`resolution`	선택	`720P` 또는 `1080P` — WAN 2.7·HappyHorse 지원
`ratio`	선택	화면비(예: `16:9`·`9:16`·`1:1`·`4:3`·`3:4`) — t2v·r2v만. i2v는 입력 이미지 비율 유지
`duration`	선택	영상 길이(초, 정수) — WAN 2.7·HappyHorse
`watermark`	선택	워터마크 표시 여부(true/false) — WAN 2.7·HappyHorse
`seed`	선택	재현용 시드(정수) — WAN 2.7·HappyHorse
`prompt_extend`	선택	업스트림 프롬프트 확장(true/false) — WAN 2.7 전용

modoo-video-happyhorse-r2v 는 reference_image_urls(1~9장)가 필수입니다. resolution·ratio·duration·watermark·seed 는 WAN 2.7(modoo-video/-i2v)과 HappyHorse 모델 모두에서 적용됩니다(각 모델이 받지 않는 값은 무시). prompt_extend 는 WAN 2.7 전용입니다.

# 이 요청은: 설명대로 영상을 만들어 달라고 접수합니다.
curl https://modoo.devdive.me/v1/videos/generations \
  -H "Authorization: Bearer sk-modoo-..." \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "잔잔한 파도가 치는 해변", "model": "modoo-video" }'

응답 예시 — job_id를 받고, 완료 후 결과에 video_url이 들어 있습니다.

{
  "job_id": "job_vid123",
  "status": "processing",
  "model": "modoo-video",
  "modality": "video",
  "charge": 2.00
}

POST /v1/audio/music — 음악 생성 (비동기)

가사를 주면 노래 한 곡을 만들어 줍니다. 시간이 걸리므로 비동기 방식입니다.

필드	필수	설명
`lyrics`	필수	노래로 만들 가사(1~3500자). 줄바꿈은 `\n`, `[Verse]`·`[Chorus]` 같은 구조 태그 사용 가능
`model`	선택	음악 엔진 버전 — `music-2.5`(기본) 또는 `music-2.0`
`prompt`	선택	원하는 분위기·스타일 설명(2000자 이하, 예: 잔잔한 어쿠스틱 발라드)
`audio_setting`	선택	출력 오디오 설정 — `sample_rate`(16000·24000·32000·44100) · `bitrate`(32000·64000·128000·256000) · `format`(`mp3`·`wav`·`pcm`). 넣지 않은 항목은 기본값

model 만 다른 엔드포인트와 의미가 다릅니다

다른 엔드포인트의 model 은 모두의창업 모델 ID(modoo-...)지만, 음악 생성의 model 은 업스트림 음악 엔진 버전(music-2.5/music-2.0)입니다. 모두의창업 모델 ID는 항상 modoo-music 이고, 응답의 model 필드에도 modoo-music 이 들어갑니다.

# 이 요청은: 가사로 노래 만들기를 접수합니다.
curl https://modoo.devdive.me/v1/audio/music \
  -H "Authorization: Bearer sk-modoo-..." \
  -H "Content-Type: application/json" \
  -d '{
    "lyrics": "가을 밤 골목길, 따뜻한 커피 한 잔",
    "model": "music-2.5",
    "prompt": "잔잔한 어쿠스틱 발라드"
  }'

응답 예시 — job_id를 받고, 완료 후 결과의 result.audio_url에 완성된 노래 파일 주소가 들어 있습니다.

{
  "job_id": "job_music123",
  "status": "processing",
  "model": "modoo-music",
  "modality": "music",
  "charge": 1.50
}

고급 사용

POST /v1/tasks/{model} — 원시(raw) 호출 (고급)

편의 엔드포인트가 따로 없는 모델(예: modoo-web-search, modoo-tts-eleven)을 쓰거나, 세부 옵션을 직접 넘기고 싶을 때 사용하는 고급 기능입니다. 주소의 {model} 자리에 모델 이름을 넣습니다.

# 이 요청은: 특정 모델에 직접 세부 옵션을 넘겨 실행합니다.
curl https://modoo.devdive.me/v1/tasks/modoo-tts-eleven \
  -H "Authorization: Bearer sk-modoo-..." \
  -H "Content-Type: application/json" \
  -d '{ "text": "안녕하세요" }'

동기 모델이면 결과가 바로 옵니다.

{
  "id": "task_abc123",
  "model": "modoo-tts-eleven",
  "modality": "tts",
  "result": { "audio_url": "https://.../out.mp3" },
  "charge": 0.10
}

비동기 모델이면 job_id를 받고, 아래 방법으로 결과를 확인합니다.

{
  "job_id": "job_abc123",
  "status": "processing",
  "model": "modoo-video",
  "modality": "video",
  "charge": 2.00
}

GET /v1/jobs/{job_id} — 비동기 작업 결과 확인

비동기(async) 란 무엇일까요? 음성 인식, 이미지·비디오 생성처럼 시간이 걸리는 작업은 결과를 바로 주지 못합니다. 그래서 다음 순서로 동작해요.

작업을 요청하면 즉시 job_id(작업 번호표) 를 받습니다.
잠시 후 이 주소로 job_id를 넣어 결과가 나왔는지 확인(폴링) 합니다.
status가 succeeded가 되면 결과를 가져옵니다.

# 이 요청은: 접수한 작업이 끝났는지 확인합니다.
curl https://modoo.devdive.me/v1/jobs/job_abc123 \
  -H "Authorization: Bearer sk-modoo-..."

응답 예시 — status를 먼저 확인하세요.

{
  "job_id": "job_abc123",
  "status": "succeeded",
  "model": "modoo-image-z",
  "charge": 2.4,
  "result": {
    "image_urls": ["https://.../image1.png"]
  }
}

status는 processing(처리 중) / succeeded(완료) / failed(실패) 중 하나입니다.
아직 processing이면 몇 초 뒤에 한 번 더 확인하세요.
없는 작업 번호이거나 본인 작업이 아니면 404가 옵니다.
charge는 이 작업에 대해 지금까지 차감된 크레딧 총액입니다. 비동기 작업은 접수 시점과 완료 시점에 나눠 과금되므로, status가 succeeded가 된 뒤의 값이 최종 금액입니다. failed면 접수 시 차감분이 환불되어 0이 됩니다.

미디어 URL은 저장하지 마세요

결과의 이미지·음성·영상 URL은 일정 시간이 지나면 만료됩니다. 따라서 URL 자체를 오래 저장하지 말고, 필요할 때 다시 조회해서 그때의 최신 URL을 쓰세요.

오류(에러) 형식

문제가 생기면 응답에 아래와 같은 형태로 이유가 담겨 옵니다.

{
  "error": {
    "code": "invalid_api_key",
    "message": "키가 틀리거나 비활성 상태입니다.",
    "type": "modoo_error"
  }
}

각 오류 코드의 뜻과 해결 방법은 오류 안내에서 자세히 설명합니다.

다음으로

여러 AI를 순서대로 이어 붙이고 싶다면 → 워크플로우
Claude·Cursor 같은 도구에 연결하고 싶다면 → MCP 연동
아직 안 해봤다면 → 빠른 시작

인증​

기본 URL​

조회 엔드포인트​

GET /v1/models — 사용 가능한 모델 목록​

GET /v1/credits — 남은 크레딧 조회​

GET /v1/usage — 최근 사용 내역​

텍스트 생성​

POST /v1/chat/completions — 텍스트 생성 (동기)​

POST /v1/chat/completions (스트리밍) — 답변을 실시간으로 받기​

멀티모달 (음성·이미지·문서·비디오)​

POST /v1/audio/speech — 음성 합성 (TTS, 동기)​

POST /v1/audio/transcriptions — 음성 인식 (STT, 비동기)​

POST /v1/images/analyses — 이미지 분석 (동기)​

POST /v1/documents/analyses — 문서 분석 (동기)​

POST /v1/images/generations — 이미지 생성 (비동기)​

POST /v1/videos/generations — 비디오 생성 (비동기)​

POST /v1/audio/music — 음악 생성 (비동기)​

고급 사용​

POST /v1/tasks/{model} — 원시(raw) 호출 (고급)​

GET /v1/jobs/{job_id} — 비동기 작업 결과 확인​

오류(에러) 형식​

다음으로​

인증