전체 참고는 내부 워커·관리 경로까지 포함합니다. 일반 연동에는 작업별 안내를 권장합니다.
GPU Console의 현재 구현 기준입니다. API가 등록되어 있어도 해당 백엔드·모델·워커 기능이 실행 중이어야 사용할 수 있습니다.
LLM에서 문서 사용
API 가이드의 LLM용 문서 복사는 선택한 작업의 요약·예제만 복사합니다. 전체 내부·관리 경로가 필요하면 전체 참고를 선택합니다. 자동 클립보드 접근이 제한되면 전체 선택해서 직접 복사할 수 있습니다. 작업별 원문은 /llms-full.txt?topic=quickstart|llm|images|audio|management, 전체 원문은 /llms-full.txt, 문서 색인은 /llms.txt이며 로그인 없이 읽을 수 있습니다. 생성된 키·세션·사용자 KB·실시간 장비 상태는 포함하지 않습니다. 문서가 공개되어도 생성 요청·이력·관리 API의 인증·권한은 그대로 적용됩니다. 공개된 생성 결과 파일 URL은 별도로 인증 없이 조회합니다.
빠른 시작
기본 주소는 https://gpu.taek.cc입니다. 이전 https://gpu.develeste.com과 https://gpu-translation.develeste.com은 호출처 이전을 위한 호환 주소입니다. API 키 값은 예시에 넣지 말고 로컬 환경 변수로 전달하세요.
export GPU_CONSOLE_URL=https://gpu.taek.cc
# GPU_RELAY_API_KEY는 발급받은 비밀값을 환경 변수로 설정
curl "$GPU_CONSOLE_URL/v1/models" \
-H "Authorization: Bearer $GPU_CONSOLE_API_KEY"
curl "$GPU_CONSOLE_URL/v1/chat/completions" \
-H "Authorization: Bearer $GPU_CONSOLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model":"gpu","stream":true,"messages":[{"role":"user","content":"안녕하세요"}]}'
인증과 키 범위
외부 추론 API는 Authorization: Bearer <key>를 받습니다. Messages와 count_tokens에 한해 x-api-key: <key>도 받으며 서로 다른 두 인증값을 함께 보내면 거절합니다. 대시보드의 승인된 사용자 세션도 추론 API에 사용할 수 있습니다.
| 키 범위 | 허용하는 기능 |
|---|
images | 이미지 생성·편집·본인 결과의 공유 설정 |
chat | chat completions |
messages | Messages, count_tokens |
audio_stt | 음성 인식, 음성 번역 |
audio_tts | 음성 합성, 음성 목록, 내 보이스 조회·샘플 듣기 |
audio_voices | 보이스 라이브러리 관리(참조 음성 업로드·설명으로 설계·이름 변경·저장·삭제) |
audio_align | 음성-텍스트 정렬(어절별 시작·끝 시간) |
bgremove | 배경 제거, 배경 제거 워커 목록 |
agent | GPU 모델의 도구 루프 /agent/chat |
* | 현재와 미래에 등록되는 모든 추론 범위 |
모든 유효한 범위의 키로 /v1/models를 읽을 수 있습니다. 새 키는 전체 scopes:["*"]가 기본값입니다. 특정 범위만 선택하면 미래 범위는 자동 추가되지 않습니다. 빈 선택은 거절합니다. 기존 빈 scope는 ['*'], 기존 Messages 전용은 ['messages']로 해석·마이그레이션하며 재발급하지 않습니다.
일반 API 키는 전체여도 관리 API를 열지 못합니다. /status, /workers, /requests, /stats/summary 등은 대시보드 세션 쿠키가 필요합니다. 관리자 표기 경로는 관리자 세션만 허용하며, 운영 대화·작업은 소유자도 검사합니다. 범위 밖은 403입니다. TRIBE와 워커 터널은 별도 공유 토큰을 사용합니다. 활성 DB API 키가 하나도 없는 초기/호환 상태에서는 /v1/models와 chat 및 오디오 4개 경로를 무인증으로 허용하는 기존 동작이 있습니다. Messages와 관리 경로는 이 예외에 포함되지 않습니다.
모델 선택과 큐 우선순위
LLM의 model:"gpu"는 사용 가능한 후보를 자동 선택하고, gpu-N은 해당 슬롯을 지정합니다. 실제 모델 ID는 해당 모델을 제공하는 워커 중 선택합니다. 설치·다운로드만 된 모델이 자동으로 목록에 추가되거나 로드되지는 않습니다. 모델 ID·capabilities·문맥 크기·가용성은 /v1/models로 확인하세요. 워커 온라인은 모델 서버 온라인과 별개입니다.
`gpu-N`은 선호입니다. 지정한 GPU가 정상이면 지금까지처럼 그 GPU에서 처리합니다. 그 GPU가 꺼져 있거나(연결 없음), 모델이 없거나, 보류(hold) 상태이거나, 연속 실패로 회로가 열렸거나, 그 모델이 요청에 필요한 입력(이미지 등)을 지원하지 않으면 릴레이가 같은 라우팅 단계 안에서(추가 왕복 없이) 다른 GPU로 폴백합니다. 지정 GPU가 모델을 알고 있으면 같은 모델을 가진 GPU를 먼저, 모델을 모르면(꺼짐·모델 없음) gpu와 같은 규칙으로 요청에 맞는 GPU를 고르며, 큐와 동시성 규칙은 그대로입니다. 지정 GPU가 정상이지만 바쁠 때는 같은 모델을 가진 다른 GPU에 빈 자리가 있으면 기다리지 않고 바로 그쪽으로, 모두 바쁘면 지정 GPU의 큐에서 기다립니다(기다리는 동안 다른 GPU가 비면 가져갈 수 있습니다). 폴백 후보는 요청이 필요로 하는 이미지 입력, 도구 호출, thinking, 문맥 길이(글자 수로 추정) 를 갖춘 것만이며, 워커가 능력 정보를 알리지 않은 항목은 제외 사유로 쓰지 않습니다. 후보가 없으면 409 gpu_unavailable에 지정 GPU의 상태와 후보별 제외 사유를 담습니다.
`gpu_strict`: 본문 `gpu_strict` > 헤더 `x-gpu-strict` > 키의 `gpu_strict` > 기본값 false 순서로 정하며, true이면 지정 GPU에서만 처리합니다. 그 GPU가 꺼져 있거나 모델이 없거나 보류 상태이면 기다리지 않고 즉시 503 `gpu_unavailable`(Messages는 overloaded_error)입니다. 바쁜 것은 불가가 아니므로 그 GPU의 큐에서 기다립니다. 릴레이 배포·워커 재접속 직후의 복구 구간(시작 후 120초, 워커가 끊긴 후 120초)에서만 지정 GPU가 돌아오기를 복구 대기 시간(기본 30초)까지 기다립니다. 장애 조치(failover)도 지정 GPU를 벗어나지 않습니다. gpu_strict는 릴레이 전용 필드라 워커와 vLLM에 전달되지 않습니다(Messages 본문에서도 제거합니다).
Messages의 폴백은 같은 모델을 가진, anthropic-messages-v1을 지원하는 다른 GPU로만 갑니다. 세션이 모델(도구·thinking·문맥)에 묶여 있으므로 모델이 다른 GPU로는 옮기지 않으며, 지정 GPU가 꺼져 모델을 알 수 없으면 404(gpu_strict이면 503)입니다.
응답 헤더 x-relay-gpu(처리한 GPU, 예 gpu-2), x-relay-model(처리한 모델), x-relay-fallback(true/false; gpu-N을 지정했는데 다른 GPU가 처리하면 true)을 스트리밍 응답을 포함해 첫 바이트 전에 보냅니다. 요청 이력에는 requested_alias, served_gpu, fallback, gpu_strict를 남깁니다. 모델 별칭으로 호출하면 x-relay-alias(별칭)와 x-relay-step(별칭 목록에서 처리한 모델의 1부터 센 위치)도 보냅니다. STT·TTS 응답에도 같은 헤더가 붙습니다.
모델 종류와 모델 별칭. 모든 모델에는 종류(llm·stt·tts)가 있고 /v1/models의 kind로 볼 수 있습니다. 종류가 맞는 호출 표면이 정해집니다: chat·Messages는 llm, /v1/audio/transcriptions는 stt, /v1/audio/speech는 tts. 모델 별칭은 관리자가 대시보드(GPU·모델 → 모델 별칭)에서 만드는 이름(예 gemma4)으로, 한 종류의 모델을 순서대로 담은 목록입니다. model에 별칭을 쓰면 목록 순서대로 시도합니다: 올라와 있지 않거나(또는 보류·능력 부족·회로 열림) 해당 요청을 처리할 수 없는 모델은 기다리지 않고 바로 다음, 올라와 있는데 모두 바쁜 모델은 별칭의 대기 시간(기본 3초, 0~60초; 배포 직후 복구 구간에는 더 길게) 뒤에 다음 모델로 넘어갑니다. 응답이 나가기 시작한 뒤에는 다른 모델로 다시 시도하지 않습니다. 어느 모델도 처리할 수 없으면 409 gpu_unavailable(모델별 이유 포함), 모델이 없는 별칭은 409 model_alias_empty, 종류가 맞지 않는 별칭은 400입니다. 별칭 이름은 워커나 vLLM에 전달되지 않고 해당 단계의 모델 ID가 전달됩니다. 모델 ID로 직접 호출하면 지금처럼 그 모델을 제공하는 워커 사이에서만 분산하고 다른 모델로 넘어가지 않습니다. gpu·gpu-N은 GPU를 가리키는 별개 형태라 별칭과 함께 쓰지 않으며(별칭 이름으로 쓸 수 없음), gpu_strict는 별칭·모델 ID에서는 의미가 없어 무시합니다. 별칭 이름은 영문 소문자·숫자·점·밑줄·하이픈(/ 금지, 64자 이하)이며 실제 모델 ID·gpu·gpu-N·llm·stt·tts와 같을 수 없습니다. 별칭을 쓰는 데 별도 권한은 필요 없고 해당 엔드포인트의 범위를 가진 키면 됩니다. 별칭 관리(생성·순서 변경·삭제·이력·되돌리기·미리보기)는 관리자 세션 전용이며 낙관적 잠금(version)을 씁니다. 요청 이력에는 requested_alias·alias_step·resolved_model이 남습니다. 자세한 규칙·API·측정은 [모델 종류·별칭](model-aliases.md)을 보세요.
클라이언트가 응답을 다 받기 전에 연결을 끊으면(스트림 중간·비스트리밍 대기 중·큐 대기 중 모두) 요청이 워커에서 취소되어 vLLM 요청도 중단되고, 점유하던 GPU 슬롯은 곧바로(수십 ms 안에) 돌아와 다음 요청이 429 없이 처리됩니다. 요청 이력에는 status: cancelled, error_code: client_cancelled와 그때까지 받은 부분 응답이 남으며, 통계의 errors_by_code에서 client_cancelled로 따로 보입니다. 이미 끝난 요청의 취소는 아무 영향이 없습니다.
모델 ID로 요청하면 그 모델을 가진 GPU 중 큐가 짧고 사용률(진행 중 ÷ 동시성)이 낮은 쪽으로 가므로, 동시성이 큰 GPU가 비례해서 더 많이 받습니다(동시성 24와 1이면 약 24 : 1).
우선순위는 background < normal < priority < highest입니다. chat과 Messages/count_tokens의 본문 `queue_priority` > 헤더 `x-queue-priority` > 키의 `messages_priority` > 경로 기본값 순서로 적용합니다. 키의 messages_max_priority를 넘으면 최대치로 낮춥니다. 예전 키의 빈 최대값은 추가 상한이 없고, 빈 기본값은 chat normal / Messages background입니다. 새 Messages 키의 초기 제안은 설정 → 라우팅에서 변경할 수 있으며, 기존 키에는 소급되지 않습니다.
요청 이력에 api_key_name, requested_queue_priority, queue_priority, queue_priority_source, priority_clamped를 남깁니다. 우선순위는 대기 순서만 정하고 실행 중 요청을 선점하지 않습니다. Messages 키 동시성은 1–8, 전체 native 기본 상한은 4, GPU당 native는 최대 1이며 기존 GPU 전체 동시성도 적용됩니다. 큐 포화·시간 초과는 429가 될 수 있습니다. 오디오·도구 루프의 내부 호출까지 이 헤더 정책이 확장되는 것은 아닙니다.
Chat completions
OpenAI 형식의 messages, stream, temperature, max_tokens, max_completion_tokens, top_p, top_k, tools, tool_choice, reasoning, reasoning_effort, response_format과 Relay 확장 enable_tool_calls, queue_priority, gpu_strict, failover, integrations, auto_continue, auto_continue_max를 받습니다. 모델이 지원하지 않는 입력·도구·추론 기능이 API 호환만으로 생기지는 않습니다.
샘플링은 요청의 명시값 > 활성화한 GPU·모델별 기본값 > 기존 호환값 순서입니다. 명시한 0도 보존합니다. temperature(0–2), top_p/min_p(0–1), top_k(0 이상 정수), repeat_penalty(0–100), presence_penalty/frequency_penalty(-2–2), max_tokens(양의 정수), reasoning을 받습니다. 활성 프로필에서 비워 둔 필드는 엔진에 전달하지 않습니다. 프로필이 없거나 꺼져 있으면 기존대로 온도 0·추론 off를 쓰며 나머지는 생략합니다. max_completion_tokens는 max_tokens보다 우선합니다.
기본값은 관리자 화면 또는 PUT /workers/{worker_id}/sampling의 sampling_defaults로 저장합니다. 로드·해제와 독립적으로 보존되며 source(모델 카드 URL)·checked_at(RFC3339)을 남길 수 있습니다. /v1/models의 capabilities.sampling_defaults에 노출되고 여러 GPU의 값이 다르면 후보별 by_route를 확인합니다. vLLM·llama.cpp/Strata(OpenAI 호환) 및 sampling-v1 워커를 대상으로 하며, LM Studio 로드 설정과 native Messages의 원래 프로토콜은 그대로 유지합니다.
응답의 gpu_relay.sampling과 요청 이력의 sampling은 {필드: {value, source}}입니다. source는 request / model_default / compat_default / engine; engine이면 value:null로 내부 기본값을 추정하지 않습니다. 이는 릴레이가 전달한 값이며 엔진의 내부 보정 결과를 보장하지 않습니다. 스트리밍은 마지막 청크를 확인하세요. 도구 루프는 단계별/최종 sampling으로 같은 정보를 제공합니다. Native Messages 이력에는 요청에서 관측한 값 또는 엔진 기본값을 기록하며 OpenAI 전용 기본값을 적용했다고 표시하지 않습니다.
engine_extra는 엔진별 객체이며, 예: {"llamacpp":{"dry_multiplier":0.8,"dry_base":1.8,"dry_allowed_length":6,"adaptive_target":0.6,"adaptive_decay":0.75}}. 일치하는 엔진에만 전달하고 모델·메시지·인증·도구 등 임의 본문 키는 허용하지 않습니다. DRY/adaptive-P는 실제 서버의 /props에 해당 키가 있는지 확인한 뒤에만 생성합니다. 확인할 수 없거나 키가 없으면 생성 전에 거절합니다. 설치된 엔진 버전별로 검증하세요. failover는 요청값 → 슬롯값 → 전역 기본값 순서이며 재시도 가능한 구간에만 적용됩니다. 이미 받은 스트림이나 실패한 도구 작업을 무조건 재실행하지 마세요. 종료가 length인 텍스트 응답은 서버 설정에 따라 이어쓰기가 적용될 수 있고 auto_continue:false 또는 X-Relay-Auto-Continue: off로 끕니다. Structured Output·도구 호출에는 이어쓰기가 제한됩니다.
SSE는 OpenAI chunk와 [DONE]을 사용합니다. OpenAI 호환/vLLM 실행기는 tools·response_format이 있어도 상류 생성 스트림을 읽고 content, reasoning_content, tool_calls를 증분 전달합니다. 도구 조각은 index별로 id·function.name·function.arguments를 조립하세요. 완전한 JSON 인자와 `finish_reason=tool_calls`를 확인한 뒤에만 도구를 실행합니다. length·오류·불완전 EOF·취소를 완료로 처리하지 마세요. 구 실행기는 도구 호출을 마지막에 한 번 보내며 새 실행기는 조각과 최종 호출을 중복 전송하지 않습니다. 부분 응답 뒤 자동 재시도는 하지 않습니다. 사용량과 종료 이유는 마지막에 오며 usage-only 상류 이벤트도 집계합니다.
response_format은 vLLM에서는 백엔드 옵션으로, LM Studio에서는 JSON 지시문·응답 검증 경로로 처리됩니다. 증분 JSON 문자열은 도착 중 유효한 JSON이 아닐 수 있고, 백엔드의 schema 지원은 별도입니다. 최종 gpu_relay 메타데이터의 worker_id, gpu_index, gpu_alias, model, requested_model로 실제 처리 대상을 확인합니다. 이 필드명은 서비스 이름 변경 후에도 유지합니다.
운영 Orca/Strata의 json_object·지원 json_schema SSE는 생성 중 content/reasoning을 즉시 보냅니다. 완료 전 조각은 잠정 출력입니다. 최종 JSON/스키마 검증을 통과한 finish_reason=stop을 확인해야 성공입니다. 문법/스키마 오류·출력 한도·불완전 EOF는 일부 내용이 도착했어도 오류이며 성공 완료나 자동 재시도를 하지 않습니다. 비스트리밍 생성 검증 실패는 422와 error.type=structured_output_failed로 반환해 게이트웨이 오류·자동 재시도와 구분합니다. 실제 계측값이 있는 오류는 최상위 usage에 한 번 담고, 취소/단절로 사용량을 모르면 만들지 않습니다. 구조화 출력과 tools/MCP 조합은 현재 Strata에서 명시적으로 거부합니다. nonstream은 전체 검증 후 반환합니다.
도구 지원 광고는 capabilities.trained_for_tool_use로 확인합니다. 일반 OpenAI 호환 서버의 기본값은 false이며 검증된 endpoint·실제 모델·Strata 모드·실시간 /props의 모델/템플릿 SHA256이 모두 일치할 때만 true입니다. 목록 갱신 중 검증 실패·템플릿 변경은 false로 돌아갑니다. 실제 모델/gpu-N/사용자 별칭에 전달하고, 여러 후보 이름과 자동 gpu는 구성원 모두가 지원할 때만 true입니다. 이미지·추론 옵션·지원 API 경로는 각각 별개이며 도구 지원이 Native Messages를 활성화하지 않습니다. 클라이언트가 모델 메타데이터를 저장한다면 /v1/models를 다시 조회해 저장 목록을 갱신하세요.
이미지 입력
GET /v1/models에서 선택한 실제 모델 또는 gpu-N의 capabilities.vision과 capabilities.modalities.input.image를 확인하세요. messages[].content에 텍스트 블록과 {"type":"image_url","image_url":{"url":"data:image/png;base64,..."}}를 함께 전달합니다. Playground도 같은 정보로 이미지 선택을 활성화합니다. 이미지가 필요한 요청은 그 입력을 지원하는 GPU로만 라우팅하며, 지정 GPU의 실제 이미지 처리를 검증할 때는 X-Relay-GPU: gpu-N, X-Relay-No-Fallback: true를 사용하세요.
OpenAI 호환 실행기는 실행 중인 서버가 모델별 architecture.input_modalities에 image를 알릴 때 비전 지원을 반영합니다. 인코더를 켜거나 끄면 다음 모델 조회에 반영됩니다. 모델 이름·모델 카드만으로 이미지 지원을 추정하지 않으며 Chat 이미지 지원이 Native Messages나 도구 호출 지원을 의미하지는 않습니다.
모델별 추론 옵션
GET /v1/models의 각 실제 모델과 gpu-N 항목은 capabilities.reasoning.allowed_options로 확인된 선택지를 제공합니다. 예: ["off","on","low","medium","xhigh"]. off만 있으면 추론을 켠다고 가정하지 마세요. 모델·서버 설정을 바꾸면 목록을 다시 조회하세요. supported_endpoints는 해당 모델의 Chat/Native Messages 지원 경로를 알립니다. gpu와 여러 워커가 제공하는 실제 모델의 추론 선택지는 후보의 공통 항목만 제공합니다. 추론 기능을 지정할 때는 옵션을 확인한 실제 모델 또는 gpu-N을 선택하세요.
Chat 호출에는 reasoning:"off|on|low|medium|xhigh" 또는 표준 reasoning_effort:"none|low|medium|high|xhigh"를 사용합니다. 두 필드가 함께 있으면 reasoning이 우선합니다. 확인된 Strata 연결에서는 none→off, high→xhigh로 전달하며 on은 서버의 기본 강도입니다. 지원하지 않는 옵션은 실행기에 의해 거절됩니다. 일반 OpenAI 호환 연결은 기본 off이며, 운영자가 실제 서버 지원을 검증하고 연결 도구의 reasoning_mode를 설정해야 노출됩니다.
응답의 최종 답변은 choices[0].message.content, 생각 과정은 choices[0].message.reasoning_content입니다. SSE도 각각 delta.content와 delta.reasoning_content로 구분합니다. 강도는 출력량의 상한이 아닙니다. max_tokens/max_completion_tokens는 서버의 생성 한도이며 생각 과정이 예산을 소모할 수 있습니다. 종료가 length면 전체 답변 완료로 판정하지 마세요.
이 계약은 Chat completions에 적용됩니다. Native Messages는 해당 워커가 실제 제공하는 경우에만 기존 Anthropic thinking 형식을 그대로 전달합니다. Chat 지원만으로 /v1/messages 지원이 생기지는 않습니다. 호출 앱은 모델별 API 호환성과 추론 선택지를 함께 확인해야 합니다.
Anthropic Messages와 토큰 수
네이티브 vLLM /v1/messages 패스스루입니다. anthropic-messages-v1 워커가 필요하며 LM Studio나 구버전 워커는 501입니다. ?beta=true, anthropic-version, anthropic-beta를 지원합니다. model과 messages, 생성에는 양수 max_tokens가 필요합니다. 알 수 없는 모델은 404로 거절합니다.
curl "$GPU_CONSOLE_URL/v1/messages?beta=true" \
-H "x-api-key: $GPU_CONSOLE_API_KEY" \
-H 'anthropic-version: 2023-06-01' \
-H 'x-queue-priority: normal' \
-H 'Content-Type: application/json' \
-d '{"model":"gpu-1","max_tokens":256,"stream":true,"messages":[{"role":"user","content":"안녕하세요"}]}'
system/content 블록·이미지·tools/tool_result·thinking을 그대로 넘기고 번역용 JSON 주입·reasoning off·이어쓰기는 적용하지 않습니다. SSE의 message_start, content_block_*, input_json_delta, message_delta, message_stop을 보존하며 헤더 수신 후 15초 ping을 보냅니다. 연결 해제는 워커 요청도 취소합니다. 실제 이미지·thinking 지원은 모델/vLLM 설정에 달렸습니다.
요청·비스트리밍 응답은 16MiB, SSE 이벤트는 2MiB, 요청 제한 시간은 15분입니다. 문맥 초과는 400 invalid_request_error와 prompt is too long 문구로 전달합니다. 오류 형식은 {"type":"error","error":{"type":"...","message":"..."}}이며 스트림 시작 후에는 SSE error로 보냅니다. count_tokens도 native 패스스루이고 백엔드 미지원이면 501이며 임의 추정하지 않습니다. native 토큰 사용량은 통계에서 완전하게 집계하지 않습니다.
Claude CLI의 ANTHROPIC_BASE_URL은 /v1 없이 origin을 쓰고 모든 모델 환경변수를 실제 로컬 모델/별칭으로 맞춥니다. ANTHROPIC_AUTH_TOKEN은 Bearer, ANTHROPIC_API_KEY는 x-api-key이며 ANTHROPIC_CUSTOM_HEADERS='x-queue-priority: normal'을 사용할 수 있습니다. 이것은 Relay 추론 키이며 운영 어시스턴트의 Codex·Claude 구독 인증과 별개입니다.
음성 인식·번역·합성
음성 인식은 multipart file 필수, model(생략 시 turbo), language, prompt, response_format(기본 json), 숫자 temperature, 불리언 condition_on_previous_text를 받습니다. 모델은 음성 워커가 실제 제공하는 ID를 확인하세요. 업로드 파일 읽기는 64MiB까지이며 큰 파일을 자동 분할하지 않으므로 그보다 작게 보내세요. 출력 포맷 지원은 백엔드에 달렸습니다.
curl "$GPU_CONSOLE_URL/v1/audio/transcriptions" \
-H "Authorization: Bearer $GPU_CONSOLE_API_KEY" \
-F 'file=@speech.wav' -F 'model=asr/qwen3-asr-1.7b' -F 'language=ko'
네이티브 STT 모델. Docker가 없는 PC(Jetson AGX Orin 등)의 관리 워커가 고정 레시피의 loopback 엔진을 시작해 광고하는 STT 모델은 위 동기 경로를 그대로 씁니다. GET /v1/models에 kind: stt로 보이는 공개 ID(nemotron-3.5-transcribe-iq4, underdog-bark-3.0, 한국어 전용 경량 notesoop-stt-ko-v1)를 model에 지정합니다. 관리자가 GPU 탭에서 해당 프로필을 로드해 두어야 하며, 로드되지 않았거나 전환 중이면 해당 모델이 없는 것으로 응답합니다. 동시 요청은 엔진별(Nemotron 4건, Bark 1건, Notesoop 4건)이며 language·response_format만 전달합니다(Bark는 영어 전용). 각 모델의 표준 규격(지원 languages·audio_formats·response_formats·max_bytes·concurrency 등)은 GET /v1/models의 stt 블록에서 조회하며, 릴레이가 이 규격으로 요청을 먼저 검사해 맞지 않으면 워커로 보내지 않고 400 invalid_request_error와 지원 값을 돌려줍니다. 로드·해제·파일 확인은 관리자 세션의 작업 승인으로만 하고 API 키로 실행할 수 없습니다. 준비 계약과 한계는 docs/native-engines.md를 따릅니다.
/v1/audio/translations는 ASR 후 LLM 번역하는 확장 API로 OpenAI의 영어 전용 번역 응답과 다릅니다. file, LLM용 model, 별도 stt_model(기본 asr/qwen3-asr-1.7b), source_language/sourceLang/language, target_language/targetLang, stt_prompt, context, gender, prompt를 받습니다. JSON에 transcribed, translated, stt, timings, gpu_relay를 반환합니다. STT와 번역 LLM이 모두 가용해야 합니다.
PC 지정(`worker_id`). 같은 모델 ID를 여러 PC가 올려 두었을 때 요청을 한 PC로 한정하려면 선택 필드 worker_id(음성 인식은 multipart 필드, 음성 합성은 JSON 필드; ID는 GET /v1/models 항목의 worker_id)를 보냅니다. 생략하면 지금처럼 그 모델을 제공하는 PC 중 여유가 있는 곳이 처리합니다. 지정한 PC가 없거나 그 모델을 올려 두지 않았거나 지금 쓸 수 없으면 다른 PC로 넘기지 않고 409 gpu_unavailable(그 PC가 바쁘면 429)로 PC ID를 담아 알립니다. 모델 별칭에는 쓸 수 없고(400) 별칭이 정한 순서를 따릅니다. 등록 로컬(Docker) 모델에서는 등록된 PC와 같아야 합니다. 대시보드의 음성 Playground는 고른 GPU를 이 필드로 보냅니다.
음성 합성은 JSON input 필수(최대 8,192자), model, voice, language, instructions, speed(0.25–4), response_format(wav 기본; pcm/mp3/flac/opus), stream을 받습니다. 결과는 오디오 바이트이며 SSE가 아닙니다. stream:true의 실제 증분 지원과 포맷은 백엔드에 달렸습니다. 음성 목록은 voices, models, default_voice를 반환하고 voice 생략 시 서버 기본값을 사용합니다.
네이티브 TTS 모델과 스트리밍. Docker가 없는 PC의 관리 워커가 게시한 음성 합성 모델(GET /v1/models에서 route_type:tts, provider:native)은 같은 POST /v1/audio/speech를 쓰고, 모델 항목의 readiness(level: ready/limited/slow/experimental, summary, realtime_factor, limits)는 그 모델이 이 PC에서 실용적인지 알려 주고, tts 블록이 표준 규격입니다: 지원 languages, max_input_chars(+ 선택 max_input_chars_non_stream: 합성이 끝나야 응답하는 엔진의 stream:false 한도), 비스트리밍 response_formats, PCM sample_rate_hz·channels·sample_format, speed_supported, concurrency, streaming_required(스트리밍으로만 합성하는 모델이면 true: stream:true가 아닌 요청은 400이고 출력은 streaming.formats만), streaming{supported, transports, formats, text_input_streaming, cancel, cancel_settle_ms}. 릴레이가 이 규격으로 input·language·voice·speed·response_format·stream을 먼저 검사해 맞지 않으면 워커로 보내지 않고 400 invalid_request_error와 지원 값을 돌려줍니다. 엔진이 다른 요청을 정리 중이거나 재시작 중이면 503 gpu_busy와 Retry-After로 곧바로 알려 주며(이 응답은 워커 장애로 세지 않음), 이미 합성 중인 모델에 동시 요청을 보내면 429 gpu_busy입니다. 규격이 스트리밍(http_chunked)을 지원하면 stream:true(+ 생략 시 기본 response_format:"pcm")로 생성되는 대로 chunked 본문의 raw PCM을 받습니다. PCM 응답에는 Content-Type: audio/pcm, X-Audio-Sample-Rate, X-Audio-Channels, X-Audio-Sample-Format 헤더가 붙습니다. 지원하지 않는 모델의 stream:true는 400입니다. 취소(연결 종료)는 streaming.cancel에 따라 즉시(immediate) 또는 최선 노력(best_effort: 엔진이 진행 중인 작업을 마칠 때까지 해당 슬롯을 cancel_settle_ms까지 점유하고, 그래도 끝나지 않으면 엔진을 재기동)입니다. 증분 텍스트 입력·WebSocket·SSE는 아직 없습니다.
모델 라이선스 (license 필드). 네이티브 STT·TTS·정렬 모델 항목(GET /v1/models)과 관리자 레시피 목록(GET /operator/native-engines/recipes)은 readiness와 나란히 license를 게시합니다. commercial은 모델 전체의 상업 사용 상태입니다: allowed(조건 없이 허용), conditional(매출 한도·사용 제한·호스팅 제외 같은 조건부), noncommercial(연구·비상업 전용, 상업 사용에는 별도 서면 라이선스 필요), unknown(원문을 읽지 않아 알 수 없음). components는 라이선스가 나뉘는 부분별 목록이고 각 항목은 role(weights 가중치, code 코드, outputs 출력, codec 코덱, other), name, spdx(있을 때), url(원문 위치), revision(원문을 읽은 40자 revision), revision_pinned(true면 워커 레시피가 그 revision 문자열을 직접 고정, false면 revision은 내려받은 파일의 기록에서 찾은 것이라 출처는 알지만 레시피가 강제하지는 않음), commercial, restriction(상업 사용을 제한하는 조건과 원문이 허용하는 예외를 함께 적은 요약, allowed가 아니면 필수), evidence(pinned_file 레시피가 고정한 파일과 대조, revision_text 해당 revision에서 원문·모델 카드 확인, none 레시피가 쓰는 부분이지만 읽지 못해 unknown으로 둠)를 가집니다. 모델 전체 commercial은 부분 중 가장 제한적인 값입니다(비상업 > 조건부 > 미확인 > 허용). 그래서 코드가 MIT여도 가중치가 비상업이면 비상업이고, 이미 아는 제한은 읽지 못한 부분 때문에 `unknown`으로 바뀌지 않습니다(가중치 비상업 + 코덱 미확인 = noncommercial, 조건부 + 미확인 = conditional). 허용인 부분과 읽지 못한 부분만 있으면 unknown입니다. 얼마나 읽었는지는 verification이 따로 말합니다: complete(모든 구성요소를 읽음), partial(일부만 읽음 — 화면은 알려진 상태를 먼저 보이고 읽지 못한 구성요소를 함께 적음), none(읽은 것이 없음, 빈 components). 범위는 레시피가 고정한 모델·코덱·코드 구성요소이며 Python 패키지나 시스템 라이브러리 라이선스는 포함하지 않습니다. 모델 이름·계열·레시피 노트로 추정하지 않습니다. 이 필드는 사용 전에 원문을 확인하도록 돕는 안내일 뿐 요청 처리와 라우팅을 바꾸지 않고 법률 자문이 아닙니다.
curl "$GPU_CONSOLE_URL/v1/audio/speech" \
-H "Authorization: Bearer $GPU_CONSOLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"model":"tts/qwen3-tts-1.7b","input":"안녕하세요","response_format":"wav"}' \
--output speech.wav
음성-텍스트 정렬(forced alignment). POST /v1/audio/alignments는 이미 아는 텍스트와 그 오디오를 주면 텍스트의 각 어절이 오디오의 몇 초에서 몇 초까지인지 돌려줍니다. 음성을 인식하지 않으므로 STT(/v1/audio/transcriptions)와 모델·권한(audio_align)·응답이 다릅니다. 모델은 GET /v1/models에서 route_type:alignment인 항목이며, alignment 블록(languages·verified_languages·auto_detect·audio_formats·max_bytes·max_seconds·max_text_chars·max_words·response_formats·segmentation·timestamp_unit·resolution_ms·concurrency)과 readiness가 한도와 구동 상태를 알려 줍니다. 요청은 multipart file(wav·flac·ogg), model, text(필수), 선택 language(ISO 639-1; 엔진은 쓰지 않으므로 생략 가능, 주면 지원 목록과만 대조), response_format(json만)입니다. 한도를 넘거나 지원하지 않는 값은 400이며 WAV는 헤더로 길이를 먼저 검사합니다. 응답:
{"model":"qwen3-forced-aligner-0.6b","unit":"seconds","segmentation":"whitespace","text_normalization":"punctuation_removed","resolution_ms":80,
"segments":[{"index":0,"word":"안녕하세요.","start":0.08,"end":0.72},{"index":1,"word":"오늘","start":0.8,"end":1.12}]}
segments는 입력 텍스트를 공백으로 나눈 순서·개수 그대로(word는 보낸 그대로, 구두점 포함)이고 시간은 오디오 시작부터의 초(밀리초 반올림)입니다. 구두점은 엔진에 보내기 전에 제거합니다(글자·숫자·결합 부호·아포스트로피만 유지, Qwen 공식 전처리와 같은 규칙): 구두점이 붙은 어절이 길이 0이 되거나 이웃과 같은 구간에 겹치는 것을 Orin에서 측정했기 때문입니다. 글자·숫자가 없는 어절(단독 대시 등)은 untimed:true로 앞 어절이 끝난 시각에 놓입니다. 엔진의 시작·끝 원시 값이 서로 어긋나면 Qwen이 공개한 보정(fix_timestamp: 가장 긴 비감소 열을 유지하고 어긋난 값을 이웃으로 채우거나 균등 분배)을 같은 규칙으로 적용하고, 움직인 값의 개수를 repaired_values에 적습니다(없으면 생략). 띄어쓰기가 없는 문자(중국어·일본어)는 글자 사이를 띄워 보내면 글자별 시간을 얻습니다. Qwen 공식 처리는 한국어·일본어를 형태소 단위로, 중국어를 글자 단위로 더 잘게 나누지만 이 API는 공백 단위만 씁니다. 엔진이 사용 중이면 동시 요청은 429 gpu_busy, 엔진이 준비 중이거나 재시작 중이면 503 gpu_busy와 Retry-After, 모델이 로드되지 않았으면 409 gpu_unavailable입니다. 정렬 오류는 워커 서킷에 세지 않습니다.
배경 제거·TRIBE·도구 루프
배경 제거는 multipart `image`와 선택 옵션을 전달하고 성공 시 이미지 바이트를 반환합니다. 업로드 기본 상한 25MiB, 기본 작업 제한 시간 300초(요청 timeout_seconds로 최대 600초), 큐 대기 60초입니다. X-Request-Id, X-Matte-Model, X-Processing-Time-Ms 등의 응답 헤더와 error.code/message/request_id 오류를 확인하세요. 전용 워커가 없으면 503입니다.
TRIBE는 inference scope와 별도입니다. TRIBE_RELAY_TOKEN(미설정 시 RELAY_WORKER_TOKEN)을 Bearer 또는 token 쿼리로 확인하며 둘 다 비어 있으면 기존 무토큰 구성을 따릅니다. /tribe/dispatch JSON의 task_id, input_url은 필수이고 input_type, original_filename을 받습니다. 기본 제한 시간은 3시간, 양수 timeout_seconds 쿼리로 조정합니다. 결과의 summary·shape·segments·base64 artifacts는 일반 채팅 응답과 다릅니다.
/agent/chat은 로컬 GPU 모델의 도구 루프이며 Codex·Claude 운영 어시스턴트와 다른 API입니다. JSON model, messages, tools(도구 이름 목록), temperature, max_output_tokens, reasoning, max_steps, stream을 받습니다. 기본 제한 시간 10분, 비스트리밍 결과는 steps, final_text, messages이며 SSE는 자체 LoopEvent의 type과 최종 done/error입니다. OpenAI/Anthropic SSE와 혼용하지 마세요. 도구·MCP 서버의 변경/테스트는 관리자 세션만 가능합니다.
관리 API 사용 시 참고
관리 API 예시는 대시보드와 같은 승인된 세션 쿠키를 사용합니다. 세션 쿠키나 비밀값을 문서·URL·공유 로그에 넣지 마세요. 로그인 쿠키는 호스트별이므로 다른 도메인으로 접속하면 다시 로그인합니다. /operator 변경 요청에 Origin 헤더를 보내는 경우 같은 호스트여야 합니다.
키 생성/편집 JSON은 name, scopes, messages_priority, messages_max_priority, messages_concurrency, gpu_strict(gpu-N 요청의 기본값)를 사용합니다. PATCH에서 생략한 필드는 유지하고 키의 ID·해시·접두사·비밀값은 바뀌지 않습니다. 폐기된 키는 편집하지 못합니다. 새 키 제안 설정의 필드는 messages_priority, messages_max_priority, messages_concurrency이며 기존 라우팅 설정과 별도로 저장합니다.
요청 이력의 from, to는 RFC3339 시각이며 KST는 +09:00을 포함해 URL 인코딩하세요. telemetry의 since, until은 Unix 밀리초입니다. telemetry history/events는 기본 최근1시간·limit480이며 결과의 resolution/샘플 시각을 함께 확인합니다. 누락·오래된 값은 사용량0을 뜻하지 않습니다. 수집 설정 JSON은 enabled/interval_seconds/raw_days/aggregate_days/event_days/max_storage_mib/collect_service_logs를 사용하며 전체 설정을 보냅니다. 초기값은 15초·원본7일·집계/이벤트30일·256MiB·서비스 로그off입니다. telemetry preferences는 metrics 배열(1–12개, 중복 불가)을 사용자별 DB에 저장하며 다른 관리자의 그래프 선택을 바꾸지 않습니다.
운영 대화의 모델은 Codex·Claude 엔진 모델입니다. GPU 실행 프로필은 로컬 모델의 worker_id, backend, model, image, container, context, gpu_memory, dtype, quantization, served_model, existing을 저장합니다. GPU·모델 → 모델 관리와 운영 어시스턴트는 같은 프로필을 사용합니다. save_profile 또는 POST /operator/profiles로 생성하고, 수정은 기존 id와 version을 포함한 save_profile 또는 PUT으로 수행합니다. 버전 충돌은409이며 다른 관리자의 프로필은404입니다. 기존 version 없는 항목은1로 읽고 첫 수정 때만 새 버전을 기록합니다. 모델 관리의 다운로드·GPU 탭의 로드/해제는 기존 jobs 계획·승인·직렬 실행을 사용합니다. 저장만으로 다운로드·로드되지 않습니다. 소유자별·GPU별 실행 프로필이며 자동으로 다른 관리자와 공유하지 않습니다. 저장된 계획은 설정 스냅샷이므로 원본 프로필의 편집·삭제로 바뀌지 않습니다. PC inspect의 cached_models는 워커가 제공할 때만 확인할 수 있고, 없으면 캐시 상태 미확인입니다. 캐시 조회는 기본 Hugging Face 캐시에 한정하며 준비 완료 표시는 파일 메타데이터 검사로 호환성·모델 로드 성공을 보장하지 않습니다. download, load, unload, pause, resume은 계획/작업 이력을 통해 실행하며 서버 실행 모드가 승인 여부를 결정합니다. 응답202나 계획 생성은 작업 성공이 아닙니다. 재접속 후 작업 상태를 먼저 확인하고 불확실한 작업을 반복하지 마세요.
Codex는 각 장비에서 독립 기기 코드 로그인을 사용하고 auth.json을 복제하지 않습니다. 로그인 응답은 verificationUrl/userCode/loginId 등 제한된 메타데이터만 담습니다. Claude는 장비별 구독 토큰/기존 로컬 인증을 사용합니다. KB는 관리자 공유이며 문서 수정·복원은 현재 version을 보내야 합니다. KB 도구가 있어도 GPU 실행 권한은 늘지 않습니다.
오류·가용성·호환 범위
일반 JSON API는 주로 error.type/message를, Messages는 Anthropic 오류를, 배경 제거는 error.code/message/request_id를 사용합니다. 인증401, 권한403, 입력400, 없는 리소스404, 상태 충돌409, 큐429, 기능 미지원501, 워커/백엔드 불가503(gpu_strict 요청의 지정 GPU 불가도 503 gpu_unavailable) 등을 구분하세요. 스트림 헤더를 이미 받은 뒤에는 오류가 스트림 안에 올 수 있으므로 HTTP200만으로 성공을 판정하지 마세요.
일부 경로는 HTML 또는 WebSocket이며 추론 JSON API가 아닙니다. LM Studio 이름의 기존 제어 경로는 vLLM용 모델 다운로드/컨테이너 관리 API가 아니며, vLLM 관리는 운영 어시스턴트의 계획·작업 경로를 사용합니다. 중지된 모델을 임의 시작하거나 ComfyUI/음성 서비스를 연쇄 재시작하지 않습니다.
단일 Pod/Recreate 배포에서 서버는 종료 전 기본3초 유예·진행 중 API 작업 최대30초 drain 후 워커에 WebSocket close1001을 보냅니다. 앞단 TCP 게이트는 새 연결을 최대75초 보류하고, 앱은 시작/워커 소실 후120초 구간에 라우팅 불가 요청을 최대30초 기다리며 큐 대기 시간(평소 queue_timeout_ms)도 그 구간에서는 복구 대기 시간까지 늘립니다. 한 GPU의 큐에서 기다리던 요청은 다른 GPU가 비면 그쪽에서 처리될 수 있습니다. 설정값은 운영 배포에 따라 달라질 수 있습니다. drain 한도를 넘는 진행 중 요청이나 게이트 대기보다 긴 장애는 끊길 수 있으므로 무중단을 보장하지 않습니다. 이미 전송한 요청을 게이트가 재실행하지 않습니다. 장기 실행/도구 작업은 요청 결과·이력 확인 없이 자동 재시도하지 마세요.
전용 서비스 연결과 통계
GET /status, GET /workers, GET /stats/summary는 추가 필드 service_workers로 TRIBE·배경제거 연결을 제공합니다. 기존 일반 워커 필드는 유지합니다. 각 항목: id, name, service, env, busy, connected_at, last_seen, 선택적 device_id·gpu_alias. 전용 워커 WebSocket의 device_id 쿼리는 명시적으로 같은 물리 장비 연결을 표시할 때 사용합니다(최대128바이트, 영문/숫자/._:-). 관리 능력을 부여하지 않습니다.
TRIBE·배경제거 호출은 이 버전 이후 provider=tribe|bgremove로 공통 요청 이력/통계에 기록합니다. 과거 호출은 복원하지 않습니다. 입력 파일/URL/결과 본문은 기록하지 않으며 TTFT/TPS는 제공하지 않습니다. TTFT 평균은 실제 표본(ttft_samples)으로만 계산합니다. gpu=unknown은 GPU 정보가 기록되지 않은 요청을 조회합니다. 현재 연결이 있어도 관리 워커가 없으면 모델 제어는 사용할 수 없습니다. 자세한 운영 절차는 docs/service-workers.md를 참조하세요.
관리자 대화의 PC 도구는 host_info, host_list_files, host_read_file, host_read_image, host_exec, host_write_file, host_send_input, host_publish_file, cancel_job이다. 인자는 host:{command,cwd,path,content,expected_sha256,description,timeout_ms,input,close_stdin,offset,limit}와 worker_id/job_id를 사용한다. 명령/파일 수정은 실행 모드에 따른 기존 작업 승인 경로를 사용하며 /operator/jobs/{id}/cancel은 실행 중인 소유 PC 명령을 중지한다. job_status의 wait_ms는0~20000이다. 대화별 /operator/sessions/{id}/attachments에 multipart(file) POST로 파일당2MiB 첨부를 올리고, turn에 attachment_ids(최대4개·합계4MiB)를 전달한다. /operator/sessions/{id}/attachments/{file_id} GET은 같은 관리자/대화에서만 다운로드할 수 있다. 운영 도구 상세.
Hugging Face 인증과 파일 다운로드
장비·인증의 Hugging Face API 토큰은 관리자·PC별로 암호화 저장하며 토큰을 대화나 셸 작업에 넣지 않습니다. 워커의 gpu-hf-v1 기능이 필요합니다. gpu_operation의 hf_status는 등록/도구 상태, hf_probe는 hf.repo/revision/files/include로 파일 접근과 목록·용량·commit을 확인합니다. hf_prepare는 별도 환경에 다운로드 도구를 준비하며 hf_download는 고정 commit의 파일1~32개를 받아 크기/체크섬을 검증합니다. 준비/다운로드는 기존 실행 모드·승인·PC별 직렬화와 job_status/cancel_job을 사용합니다. HF 파일 다운로드는 GPU 모델 로드나 요청 보류를 수행하지 않습니다.
운영 에이전트는 model_sampling으로 GPU·실제 모델별 기본값/version을 읽고 save_model_sampling의 최신 expected_version으로 저장합니다. test_model_sampling은 API 키 없이 공개 Chat 핸들러로 지정 GPU의 JSON/SSE·기본값 생략/명시0·요청 이력을 시험하며 max_tokens는 기본32/최대8192입니다. request·response.gpu_relay.sampling·history_saved/history_sampling·backend_readback을 반환합니다. sampling_test.prompt(최대8000바이트)·timeout_ms(최대180000)를 지정할 수 있고, SSE도 response.choices.message에 전체 본문을 반환합니다. reasoning_defaults 모드별 기본값과 sources 복수 출처를 저장할 수 있습니다. 엔진 관측은 best_effort이며 비지원이면 available:false입니다. Plan에서 저장/시험하지 않고 보류 GPU를 기동하지 않습니다.
운영 어시스턴트의 gpu_operation action verify_model은 worker_id와 실제 model ID로 Console의 모델 등록 및 지정 GPU 경유 짧은 추론을 검증합니다. 반환값 verified, advertised, inference, checked_at, reason으로 완료 여부를 판단하며 다운로드·기동·설정 변경을 대신하지 않습니다. Plan 및 보류 GPU는 추론하지 않고 미검증 상태를 반환합니다.
긴 문맥의 스트리밍 연결
Chat SSE는 모델 응답이 없는 동안 15초마다 주석 : keep-alive를 전송합니다. 주석은 답변·TTFT·토큰 사용량·성공 완료가 아닙니다. 지원되는 1M Strata 연결에서 큰 텍스트 입력은 크기에 맞춰 첫 응답 대기를 늘리며 상한은 30분입니다. 짧은 입력과 다른 모델의 기본 대기 시간은 유지합니다. 장문은 stream:true를 사용하세요. 비스트리밍 호출은 외부 프록시의 대기 한도에 걸릴 수 있습니다. 1M 광고는 실제 서버 설정 및 장문 검증이 끝난 후에만 적용합니다.
Brave Search
Console 관리자 로그인에서 GET /operator/search/brave는 내 API 키 등록·도구 활성 상태만 반환합니다. PUT의 {api_key}는 검색1회로 확인한 뒤 관리자별 기존 AES-GCM 저장소에 암호화하고, DELETE는 내 키만 삭제합니다. 응답·도구 설정·PC에는 원본 키를 전달하지 않습니다. 다른 관리자·Relay API 키 호출에 관리자 키를 공유하지 않습니다.
운영 어시스턴트 /operator/tools의 action: "brave_search", search: {query,count,freshness}와 로컬 모델 에이전트 builtin brave_search는 같은 서버 검색을 사용합니다. 관리자 쿠키로 /agent/chat 호출 시 사용할 수 있고 설정 → 에이전트 도구에서 테스트·활성화/비활성화합니다. 도구 행의 API 키 설정에서 비공개 입력란으로 이동합니다. 검색어400자·50단어, 결과1~10개(기본5), 선택기간 pd/pw/pm/py, 한국어/한국 기본 검색입니다. 제목·URL·요약을 반환하며 출처를 인용하고 결과를 지시문으로 취급하지 않습니다. 고정 HTTPS endpoint·15초/512KiB 한도, 리다이렉트/자동 재시도 없음. 미등록·인증·쿼터·취소/상류 오류는 성공으로 처리하지 않습니다. 등록·검색은 Brave 요금/쿼터를 사용합니다. 공식 인증 계약.
ComfyUI 업데이트·GitHub 연결
gpu-comfy-update-v1 실행기의 /operator/tools에서 comfy_updates_status(조회), comfy_update_preview(계획), comfy_update_discard(미실행 계획 취소), comfy_update(승인한 계획 실행)를 사용합니다. 계획에는 kind(comfyui/node/control), 최신 expected_version, 선택 node/target을 지정하고 완료될 때까지 상태를 조회합니다. 실행에는 plan_id와 plan_hash가 필요합니다.
계획은15분 또는 실행기 재시작 뒤 만료되며 완료·오래된 계획은 정리됩니다. 승인한 source/target 커밋과 태그를 PC에서 다시 확인합니다. 계획 조회나 planned 상태를 업데이트 완료로 판단하지 마세요. Default/Safe YOLO/YOLO/Plan은 서버에서 적용합니다.
긴 업데이트에는 갱신 가능한 제어 연결이 필요합니다. 구 제어 노드는 control 준비 작업을 검토·승인하고 생성·대화 유휴를 확인한 뒤 ComfyUI만 재시작합니다. 기능 배포가 본체·노드의 자동 업데이트를 뜻하지 않습니다. 멈춘 노드는 유지하고 본체 의존성 검사는 실행 중 컨테이너가 필요합니다. recovery_required이면 유지보수를 유지하며 PC 복구 기록을 확인하고 자동 재시작·재실행·잠금 해제를 하지 않습니다. 오류·rolled_back·복구 명령은 작업 결과에 남습니다.
GET /operator/devices/{id}/github-auth는 실제 사용 계정·범위·Git 자격 도우미·OS 사용자/HOME·비공개 노드 저장소 접근만 반환합니다. start는 PC에서 기기 코드 로그인을 시작하고 소유자에게 일회용 코드·GitHub 승인 주소만 반환합니다. 기존 계정 재인증은 reauthorize:true, 취소는 login_id, setup은 PC의 Git 도우미 연결입니다. 토큰을 PC 밖으로 보내거나 다른 PC에 복사하는 API는 없습니다. 로그인과 저장소 권한은 별도로 확인합니다.
Codex 구독 이미지 API
홈서버의 독립 Codex CLI가 ChatGPT 구독 사용량으로 이미지를 만듭니다. GPU·ComfyUI·모델 슬롯은 사용하지 않습니다. API → Codex 이미지 API에서 서비스 전용 기기 코드 로그인을 연결하며 다른 Codex·Tping·Kneelish 인증은 유지합니다. 인증 토큰은 홈 Codex만 보관합니다.
비동기 접수와 결과
| 메서드 | 경로 | 인증 | 기능 |
|---|
| POST | /v1/images/jobs | images 범위 API 키 또는 관리자 | 생성 작업 접수, HTTP 202·작업 ID |
| POST | /v1/images/generations | images 범위 API 키 또는 관리자 | 동일한 비동기 접수의 별칭, HTTP 202 |
| GET | /v1/images/jobs | images 범위 API 키 또는 관리자 | 생성 이력 목록, limit=1~100·before 페이지 이동 |
| GET | /v1/images/jobs/{id} | images 범위 API 키 또는 관리자 | 작업 상태·오류·완료 결과 경로 |
| GET | /v1/images/jobs/{id}/result | images 범위 API 키 또는 관리자 | 완료 이미지의 created·data[0].b64_json·실제 크기·Codex 턴 사용량 |
| GET | /v1/images/jobs/{id}/image | images 범위 API 키 또는 관리자 | 저장된 PNG 다운로드 |
| GET | /v1/images/jobs/{id}/inputs/{index} | images 범위 API 키 또는 관리자 | 저장한 참조 이미지 조회·소유권 확인 |
| POST | /v1/images/jobs/{id}/cancel | images 범위 API 키 또는 관리자 | 대기 취소 또는 진행 중 취소 요청 |
| DELETE | /v1/images/jobs/{id} | images 범위 API 키 또는 관리자 | 완료/실패/취소 이력과 저장 이미지 삭제 |
| GET | /v1/images/status | images 범위 API 키 또는 로그인 | 연결 여부·병렬 수·생성/대기 수·대기 상한 |
| GET | /operator/image-service | 관리자 세션 | 계정·플랜·본인 기기 코드·실행기 설정 |
| POST | /operator/image-service/start | 관리자 세션 | 전용 기기 코드 연결 시작 |
| POST | /operator/image-service/cancel | 관리자 세션 | 본인 login_id 연결 취소 |
| POST | /operator/image-service/logout | 관리자 세션 | 접수/진행 작업이 없을 때 연결 해제 |
| PUT | /operator/image-service/config | 관리자 세션 | 병렬 수·대기 상한 즉시 저장·반영 |
curl https://gpu.taek.cc/v1/images/jobs \
-H "Authorization: Bearer $GPU_CONSOLE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: caller-request-001" \
-d '{"model":"codex-image","prompt":"햇살이 비치는 카페의 일러스트","n":1}'
접수 응답은 id, status=queued, status_url을 반환합니다. 상태는 queued/running/cancelling/succeeded/failed/cancelled/unknown입니다. succeeded의 result_url 또는 image_url로 결과를 받습니다. HTTP 연결을 닫거나 페이지를 새로고침해도 접수한 작업은 취소되지 않습니다. 취소는 별도 API로 요청합니다. API 키는 같은 키가 접수한 작업만 조회·취소·삭제하고, 관리자는 화면·API 키의 전체 이력을 볼 수 있습니다.
같은 소유자·Idempotency-Key·요청 내용은 기존 ID를 반환하며 다르면 409입니다. 실패·응답 유실·앱 재기동 때문에 결과가 불확실한 작업을 자동 재생성하지 않습니다. 생성 전에 running 상태를 DB에 저장하고, 재기동 시 미시작 queued만 이어 처리합니다. running/cancelling 복구는 unknown으로 남깁니다. 삭제 후 요청 키 중복 방지는 24시간 유지합니다. 호출자는 논리적 요청마다 새 키를 만들고 네트워크 재시도에만 같은 키를 사용해야 합니다.
prompt는 UTF-8 16000바이트 이하, n=1, model=codex-image, response_format=b64_json입니다. size는 auto, 가로:세로 비율(예: 4:3·3:4·2:1·21:9), 또는 가로x세로 픽셀(예: 1200x628)이며 background는 auto/opaque/transparent입니다. 비율은 1:3~3:1, 픽셀 크기는 각 변 64~4096px·총 8,388,608픽셀 이하로 제한합니다. 크기를 지정하면 기약 비율을 생성 프롬프트에 전달한 뒤 비율 유지 리사이즈·중앙 크롭으로 정확한 픽셀 크기의 PNG를 보관합니다. 비율만 지정한 경우 실제 생성 크기를 반환합니다. image의 source_width/source_height·resized/cropped에서 원본 크기와 후처리를 확인할 수 있습니다. 확대는 원본의 세부 품질을 높이지 않습니다. Codex I2I는 images에 순서대로 {base64:...} 또는 {url:...}를 전달합니다. /v1/images/edits는 JSON 또는 반복 image/image[]·image_url multipart도 받습니다. 서비스 상한은5장(PNG/JPEG/WebP 장당8MiB·8MP, 전체24MiB·32MP)이며 /v1/images/status의 service.max_reference_images로 실행기 지원을 확인합니다. 고정 CLI0.163.0의 image_gen에서 실제로 관측한 referenced_image_paths 상한은5개입니다. app-server 입력 개수나 OpenAI Images API의16개와는 다릅니다. size_policy:input_1k/input_2k/input_original과 reference_image_index도 지원하며 직접 size와 함께 사용하지 않습니다. 참조 입력은 임시 localImage 파일로 한 번의 Codex turn에 전달하고 종료·취소 뒤 제거합니다. n>1·stream=true·미등록 옵션은 접수 전에 거절합니다. 생성 API의 최종 계약은 202 비동기 접수이며, 대기 중 HTTP/SSE 연결을 유지할 필요가 없습니다.
이력·파일·한도
요청 내용·상태·오류·사용량·이미지 참조는 기존 PostgreSQL에 저장해 기존 DB 자동 백업을 따릅니다. 출력 PNG는 image-jobs, 입력은 media-inputs 접두사로 기존 SeaweedFS 전용 버킷에 보관하며 SQL/Pod 로컬에 본문을 넣지 않습니다. 생성 이미지 출력은 전용 R2 파일 백업에서 제외합니다. DB 이력과 기존 첨부·입력·음성 백업은 유지합니다. 목록은 최근 20건부터 페이지로 조회하며 삭제 전에는 이력을 보존합니다. 다음 페이지는 응답의 next_before 값을 그대로 사용하고 시간은 Unix 밀리초입니다. 이미지 다운로드는 동시에 8개로 제한하며 초과 시 429 IMAGE_DOWNLOAD_BUSY/Retry-After:1을 반환합니다. 결과 재조회는 새 이미지를 생성하지 않습니다. 전체 5000건·10GiB, 소유자별 1000건·2GiB 한도이고 진행 작업은 출력당 최대32MiB와 저장한 입력 파일 크기를 함께 예약합니다. 한도 초과는 429 IMAGE_QUEUE_FULL 또는 IMAGE_HISTORY_LIMIT입니다. 실패 작업과 불확실한 결과를 정상 완료로 표시하지 않습니다. 실패의 error.code와 선택적 error.provider_note를 상태·이력에 보관합니다. provider_note는 Codex 모델의 설명이며 상위 도구가 확정한 원인 코드와 구분합니다. 토큰·인증 URL·로컬 경로는 제외하며, 상세 원인이 없으면 추측하지 않고 미제공으로 표시합니다. 실패·불확실 작업은 자동 재생성하지 않습니다.
결과 URL과 공개 설정
생성 이미지 결과는 기본 공개·무제한입니다. 기존 갤러리의 생성 결과에도 적용합니다. 완료 응답의 image_url(홈 Codex) 또는 file_url(로컬 이미지)은 로그인·API 키 없이 브라우저나 <img src="...">에서 바로 열리는 절대 URL입니다. share_url은 같은 공개 주소이며 공개 상태에서만 제공합니다. 원본 파일 주소는 authenticated_image_url 또는 authenticated_file_url로 따로 제공합니다. 비공개·만료 결과는 기존 인증용 주소로 조회합니다.
생성 접수·이력 조회·공유 설정 변경은 API 키가 필요하며, 해당 키로 접수한 작업만 관리합니다. 관리자는 갤러리에서 전체 생성 결과를 관리합니다. 입력·참조 이미지와 대화 첨부는 공개하지 않습니다. 음성 결과는 기존 인증 조회를 유지합니다.
생성 요청 JSON의 선택 항목 sharing으로 정책을 정합니다. 생략하면 공개·무제한입니다.
| 요청 옵션 | 동작 |
|---|
생략 또는 {"visibility":"public"} | 공개·무제한 |
{"visibility":"private"} | 비공개·소유자/관리자만 조회 |
{"visibility":"temporary","expires_in":86400} | 접수 시각부터1일 공개 |
expires_in은 초 단위이며0은 무제한, 기간 공유는1~31536000초입니다. {"expires_in":3600}도1시간 공유로 해석합니다. 기간 만료는 원본 파일을 삭제하지 않습니다. 공유 설정은 생성 실행기에 전달하지 않으며 이미지 생성 옵션/화질에 영향을 주지 않습니다. multipart 편집에서는 sharing 폼 필드에 같은 JSON 문자열을 넣습니다.
생성 후에도 다음 경로를 사용합니다. 아래 {job_path}는 Codex의 /v1/images/jobs/{id} 또는 로컬 이미지의 /v1/media/jobs/{id}입니다.
| 메서드 | 경로 | 인증 | 기능 |
|---|
| GET | /v1/images/jobs/{id}/share | images 범위 API 키 또는 관리자 | 공유 상태·기한·주소 조회 |
| PUT | /v1/images/jobs/{id}/share | images 범위 API 키 또는 관리자 | 공개·비공개·기간 설정 |
| DELETE | /v1/images/jobs/{id}/share | images 범위 API 키 또는 관리자 | 공유 해제·원본/이력 유지 |
| GET | /v1/media/jobs/{id}/share | images / videos 범위 API 키 또는 관리자 | 공유 상태·기한·주소 조회 |
| PUT | /v1/media/jobs/{id}/share | images / videos 범위 API 키 또는 관리자 | 공개·비공개·기간 설정 |
| DELETE | /v1/media/jobs/{id}/share | images / videos 범위 API 키 또는 관리자 | 공유 해제·원본/이력 유지 |
| GET | /generated-media/{id}/{token} | 인증 없음·공개 상태와 주소 검증 | 생성 결과 직접 조회·HEAD/Range 지원 |
# 완료 작업을1시간 공유로 변경
curl -X PUT "$GPU_CONSOLE_URL/v1/images/jobs/$JOB_ID/share" \
-H "Authorization: Bearer $GPU_CONSOLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"visibility":"temporary","expires_in":3600}'
# 응답 share_url은 인증 헤더 없이 브라우저에서 직접 조회
응답 sharing은 visibility·state·expires_at(Unix 밀리초,0은 무제한)·공유 중일 때 url을 담습니다. 상태는 public, temporary, private, expired, 미완료/삭제 때 unavailable입니다. 이미지 생성 중에는 아직 외부 결과 주소를 제공하지 않으며 완료 상태를 조회하세요. 설정을 변경하거나 재공유하면 새 주소를 발급합니다. 복사는 기존 주소를 유지합니다. 해제한 옛 주소는 다시 공유해도 살아나지 않습니다. 같은 Idempotency-Key의 생성 재요청은 공유 상태를 되돌리거나 이미지를 다시 생성하지 않습니다.
공개 URL은 해당 결과 파일만 GET/HEAD/Range로 제공합니다. 목록·프롬프트·입력 파일은 노출하지 않습니다. 만료·비공개·삭제·잘못된 주소는404이며, 공유 해제 전에 내려받은 사본이나 이미 전송 중인 응답까지 회수하지는 않습니다. 브라우저/CDN에 장기 캐시하지 않도록 private, no-store를 사용합니다. SeaweedFS 버킷과 영구 저장소 키는 비공개로 유지합니다.
실시간 설정
화면에서 병렬 CLI 1~8개, 대기 수 상한 0~1000개를 바꾸면 재시작 없이 즉시 적용합니다. 기본은 병렬 2개·대기 16개이며, 저장값은 홈 실행기 재기동 뒤에도 유지합니다. 직접 변경은 PUT /operator/image-service/config의 {"processes":4,"max_queue":32}로 하며 한 필드만 바꿀 수도 있습니다. 늘리면 대기 요청을 처리하고, 줄이면 진행 중 생성·이미 접수한 대기는 보존한 채 새 요청부터 한도를 지킵니다. 대기 0은 빈 실행 슬롯만 접수합니다. 병렬 CLI는 같은 구독 한도를 공유합니다.
이미지 API 키로 인증·실행 설정을 바꿀 수 없습니다. 기존 명시적 API 범위는 그대로이고 와일드카드는 기존 정책대로 새 추론 기능을 포함합니다. 대기/진행 작업이 있으면 계정 변경을 막습니다. 실사용 구독 이미지 생성·한도는 별도이며, 기기 코드 발급이나 모의 이미지 시험을 실제 이미지 생성 성공으로 간주하지 않습니다.
로컬 이미지·음성 공통 작업 API
로컬 이미지 생성은 ComfyUI 등록 워크플로를 사용합니다. 모델·서비스에서 이미지 모델을 등록하고 T2I/I2I 기본 워크플로를 연결합니다. 기본 템플릿이나 ComfyUI AI Agent의 API 메뉴에서 내보낸 설정을 가져와 모델 파일·해시 검사 → 초안 저장 → Playground 시험 → 성공 결과 확인 후 발행합니다. 모델 파일은 GPU별 상대 파일명과 SHA256 자산으로 연결하며 등록한 모델·인코더·VAE·샘플러를 다른 것으로 대체하지 않습니다. 음성 STT/TTS는 기존 전용 엔진을 유지합니다. LoRA는 원본 HF 저장소·파일로 먼저 고정 해시를 확인하고 등록→다운로드·설치할 수 있습니다. 기존 PC 파일을 연결할 때는 원본 저장소를 비우고 ComfyUI 상대 파일명을 검사합니다. 실제 호환성과 효과는 Playground에서 확인하세요.
생성 본문은 선택적 workflow(등록 ID), workflow_version을 받습니다. 쿼리 workflow와 본문 값이 충돌하면400입니다. 생략하면 모델×작업의 발행 기본값을 사용합니다. 새 초안을 편집해도 기존 발행본과 접수한 작업은 유지됩니다. /v1/media/models의 workflows는 발행된 이름·버전·참조 한도·LoRA 지원을 제공합니다. 미발행 시험은 관리자 전용 workflow_preview:true이며 일반 생성 키에는 허용하지 않습니다.
Playground의 ComfyUI 전환 버튼은 선택 GPU의 LLM 요청을 배출하고 기존 LLM만 정지한 뒤 ComfyUI를 시작·재사용합니다. 다른 GPU·개인 큐·별도 음성 컨테이너는 중단하지 않습니다. 모드 종료는 개인 Comfy 작업이 비었는지 확인하고 이전 LLM을 복귀시킵니다. 이미 사용 중인 ComfyUI 인스턴스는 재사용하며 모델 캐시는 ComfyUI가 관리합니다. 각 GPU는 Console 작업을 한 개씩 Comfy 큐로 전달하고, 결과 파일 확보 후 별도 전송 슬롯에서 홈 저장소에 올립니다. 업로드 실패는 파일 전송만 재시도하며 생성하지 않습니다.
용어. 이 문서의 'API 모드'(media_start·media_release, 응답의 api_mode_off·lane)는 대시보드에서 미디어 실행기(Docker로 이미지·영상·등록 음성 모델을 실행) 전환을 뜻하며 API 이름·필드 값은 그대로입니다. 꺼진 상태는 'LLM 모드'가 아니라 일반 모델 실행(LLM과 네이티브 STT·TTS가 요청을 받는 기본 상태; 모델이 하나도 없어도 이 상태)이고, 켜진 동안에는 그 GPU의 LLM과 네이티브 STT·TTS 요청이 보류되며 그 모델의 로드·해제가 잠깁니다(서버가 거절). Docker에 등록한 모델이 없는 PC에는 전환 동작이 없습니다. STT/TTS는 실행 환경 준비·모델 다운로드 후 전용 이미지·음성 API 모드를 사용합니다. 음성 모드와 ComfyUI 이미지 모드를 동시에 같은 전용 실행기로 처리하지 않습니다. 각 GPU1건·전체 동시 GPU1~3·대기0~1000 설정은 유지합니다.
curl "$GPU_CONSOLE_URL/v1/media/jobs" \
-H "Authorization: Bearer $GPU_CONSOLE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: my-image-001' \
-d '{"model":"qwen-image-21-turbo","task":"t2i","prompt":"A quiet seaside cafe","width":1024,"height":1024,"steps":8,"seed":42}'
I2I는 task:i2i와 images 배열을 사용합니다. 과거 단일 image_base64는 호환용이며 함께 보내지 않습니다. Qwen 2.1/Turbo는 참조 이미지 편집이며 strength를 받지 않습니다. Turbo는 고정8스텝·CFG1·제외 프롬프트 없음, 결과는32배수·각변256~3072px·총4.5MP 이하입니다. SDXL은 strength(0.01~1), 8배수·각변256~1536px·총1.5MP 이하, 스텝1~80·guidance0~20·negative_prompt를 지원합니다. 시드는0~4294967295입니다. LoRA의 트리거는 prompt에 넣으세요. STT는 audio_base64·선택 language를 사용하며 WAV/MP3/WebM 등 PyAV가 해석할 수 있는 음성12MiB·10분 이하를 받습니다. TTS는 text·voice(기본sohee)·language(기본Korean)·선택 instructions를 받으며 결과는 PCM16 WAV입니다. Qwen CustomVoice의 지원 목소리와 언어만 사용할 수 있습니다.
{"model":"qwen3-tts","task":"tts","text":"안녕하세요. 반갑습니다.","voice":"sohee","language":"Korean"}
GET /v1/media/jobs/{id}를 폴링하고 succeeded일 때 file_url로 PNG/WAV/JSON을 받습니다. STT 결과는 상태의 text에도 있습니다. 결과에 고정 모델/LoRA와 시드·실측 처리 시간·GPU 메모리 정보가 기록되며 실제 지원 필드만 반환합니다. 입력 파일은 비공개이며 결과 이미지는 기본 공개·무제한 URL을 반환합니다. 파일은 비공개 SeaweedFS에 저장하고 공개 게이트웨이가 파일별 공유 정책을 확인합니다. 작업·오류·소유권은 PostgreSQL, 처리 요청은 통합 로그에 남고 이미지 base64 본문은 기록하지 않습니다. 전체5,000건·10GiB 및 계정·키별1,000건·2GiB에서 접수를 제한하므로 불필요한 이력은 삭제하세요. 입력 파일도 저장 한도에 포함됩니다.
queued/running/uploading/cancelling은 미완료입니다. ComfyUI는 job별 prompt ID로 상태를 확인하고 해당 prompt만 취소합니다. 전역 interrupt나 ComfyUI 컨테이너 강제 중지로 대체하지 않습니다. 홈 업로드를 확인한 뒤 자기 API 임시 파일만 지웁니다. 아래 전용 컨테이너 중지 정책은 기존 음성 엔진에만 해당합니다. 취소는 대기 작업을 즉시 제거하고, 실행 작업은 엔진의 안전한 경계에서 취소합니다. 30초 내 반응이 없으면 전용 이미지·음성 컨테이너만 중지합니다. 이때 LLM 요청 보류는 유지되며 명시적으로 API 모드를 종료해 복구하세요. 실패·연결 유실·서버 재시작으로 결과가 불확실한 작업은 failed/unknown으로 남고 자동 재생성하지 않습니다. 동일한 Idempotency-Key와 요청은 같은 작업 ID를 반환하고 다른 내용은409입니다. 키 없이 재요청하면 새 작업입니다. 대기열 초과는429·Retry-After를 반환합니다.
기존 /v1/images/generations는 model이 codex-image이면 기존 Codex 경로, 등록한 로컬 이미지 ID이면 로컬 비동기 T2I 경로입니다. 로컬의 size는 1024x1024, n은1만 허용합니다. /v1/images/edits는 로컬·Codex의 I2I JSON 또는 multipart image/model/prompt를 받습니다. 나머지 옵션은 선택 모델의 계약을 따릅니다. 등록한 STT/TTS 모델을 기존 /v1/audio/transcriptions·/v1/audio/speech에 지정하면 역시 202 작업을 반환합니다. 로컬 STT는 json 결과, TTS는 WAV를 반환하며 목소리·속도 옵션은 모델별 speech 메타데이터를 따릅니다. 스트리밍은 지원하지 않습니다. 등록하지 않은 기존 음성 워커의 동기 응답 계약은 유지됩니다. 공통 작업 API는 OpenAI의 동기 응답과 다르므로 Location을 폴링해야 합니다.
공통 모델·작업·결과
| 메서드 | 경로 | 인증 | 내용 |
|---|
| GET | /v1/media/models | images / videos / audio_stt / audio_tts / 관리자 | 등록 모델·종류·엔진·작업 목록 |
| POST | /v1/media/jobs | images / videos / audio_stt / audio_tts / 관리자 | task별 권한 검사 후 비동기202 접수 |
| GET | /v1/media/jobs | images / videos / audio_stt / audio_tts / 관리자 | 소유 이력; limit1~100·offset |
| GET | /v1/media/jobs/{id} | images / videos / audio_stt / audio_tts / 관리자 | 작업 상태·오류·결과 경로 |
| GET | /v1/media/jobs/{id}/poster | images / videos / audio_stt / audio_tts / 관리자 | 영상 대표 PNG; 작업별 videos 권한·소유권 검사 |
| GET | /v1/media/jobs/{id}/result | images / videos / audio_stt / audio_tts / 관리자 | 완료 결과 메타데이터·텍스트 |
| GET | /v1/media/jobs/{id}/file | images / videos / audio_stt / audio_tts / 관리자 | 완료 PNG/MP4/WAV/JSON 다운로드 |
| GET | /v1/media/jobs/{id}/inputs/{index} | images / videos / 관리자 | 소유한 작업의 입력 이미지 조회·0부터 시작 |
| POST | /v1/media/jobs/{id}/refresh | images / 관리자 | ComfyUI의 불명 작업을 같은 prompt ID로 상태만 재확인; 재생성 없음 |
| POST | /v1/media/jobs/{id}/cancel | images / videos / audio_stt / audio_tts / 관리자 | 대기 취소·실행 취소 요청 |
| DELETE | /v1/media/jobs/{id} | images / videos / audio_stt / audio_tts / 관리자 | 종료 작업과 입력·출력 삭제 |
| POST | /v1/images/edits | images / 관리자 | 로컬 I2I 비동기202 접수 |
| GET | /operator/media/models | 관리자 | 고정 모델·LoRA 레시피 |
| POST | /operator/media/probe | 관리자 | PC에서 저장소·리비전·필요 파일 확인 |
| POST | /operator/media/models | 관리자 | 확인한 모델 등록 |
| DELETE | /operator/media/models/{id} | 관리자 | 사용 중이 아닌 모델 등록 해제; 캐시 보존 |
| GET | /operator/media/workers/{id} | 관리자 | 실행 환경·모드·설치·작업 진행 |
| GET | /operator/media/config | 관리자 | 동시 GPU·대기 상한 |
| PUT | /operator/media/config | 관리자 | 설정 즉시 저장 |
| GET | /operator/media/logs/{id} | 관리자 | PC의 작업 로그(최대64KiB) |
Qwen Image 2.1·Turbo의 옵션
Qwen Image 2.1 Turbo의 기본 워크플로는 ComfyUI의 검증한 INT8 모델·8B 텍스트 인코더·VAE·8스텝 스케줄을 고정합니다. guidance:1, 제외 프롬프트·denoise strength 없음이며 T2I와 최대10참조 I2I를 지원합니다. 크기는32배수·256~3072/총4.5MP 이하입니다. 실제 선택한 워크플로의 max_reference_images·fixed_parameters를 모델 목록에서 확인하세요.
기본 I2I 워크플로는 참조마다2MP로 전처리하고 첫 참조 비율의 latent를 사용합니다. 입력 원본은 유지하며 지정 출력 크기가 다르면 생성 뒤 비율 유지 리사이즈·중앙 크롭합니다. metadata의 render_width/render_height는 실제 생성 크기, width/height는 반환 크기입니다. LoRA는 같은 PC의 정확한 기반 모델·파일 해시와 연결하며 실제 시각 효과는 시험해야 합니다.
FLUX.3 Image Klein의 옵션
ComfyUI의 INT8 Klein 모델·4B 텍스트 인코더·FLUX2 VAE를 사용합니다. 기본 T2I는 별도9B 프롬프트 보정 모델을 포함한 워크플로이며, 기본 I2I는 입력한 최종 장면 설명을 직접 사용합니다. 숨은 설정 전환 없이 선택한 그래프·파일 해시·버전을 이력에 보관합니다. 사용자 워크플로는 다른 이름으로 등록·시험·발행한 뒤 workflow로 선택하세요.
T2I와 최대10참조 I2I,16배수·256~2048/총2MP, steps4~16(기본16)을 지원합니다. guidance:1, 제외 프롬프트·denoise strength·미검증FLUX LoRA는 받지 않습니다. 기본 참조 전처리는 장당1MP입니다. Qwen LoRA를 FLUX에 연결할 수 없습니다. gated 원본은 해당 계정의 HF 접근 승인이 필요합니다.
마지막 모델 유지·교체·메모리 해제
이미지 모델과 LoRA 캐시는 기존 ComfyUI가 관리합니다. 매 요청마다 새 Diffusers 프로세스를 띄우지 않습니다. 같은 그래프 구성은 캐시를 재사용하고 다른 모델은 ComfyUI의 메모리 정책에 따라 올리거나 내립니다. GPU·ComfyUI 관리의 메모리 해제는 진행 중인 개인·API 작업이 비었을 때만 실행합니다. API 종료는 원래 실행 중이던 ComfyUI를 유지하고 캐시를 해제하거나, 원래 중지 상태였으면 중지한 뒤 이전 LLM 상태로 돌아갑니다.
음성 STT/TTS의 전용 실행기는 기존 마지막 모델 유지·교체·media_unload 정책을 사용합니다. ComfyUI 이미지 캐시와 음성 resident 정보는 구분합니다. 이미지 이력의 생성·대기·전송·전체 경과 시간과 실제 생성/반환 크기를 확인하세요. 서로 다른 그래프·GPU·캐시 상태의 시간을 같은 조건의 성능 비교로 해석하지 마세요.
음성 모델의 언어·목소리 기능
GET /v1/media/models, /v1/models의 등록 TTS 모델 및 GET /v1/audio/voices?model=등록모델ID는 speech 계약을 제공합니다. schema_version, ISO 언어 코드 languages, default_language, default_mode, modes, voices, options, reference_audio, license, commercial_use를 확인하세요. 각 mode의 languages·fields·required가 요청 가능 범위입니다. 미지원 언어·옵션·모드는 HTTP400이며 조용히 무시하지 않습니다.
공통 필드는 voice_mode, language, voice(화자 ID), voice_description, instructions, reference_audio_base64, reference_text, emotion, speed, pitch, volume, duration_seconds입니다. 속도·높이·볼륨은 모델의 enum(slow/normal/fast, low/normal/high)이며 물리 배수나 수치를 보장하지 않습니다. 감정·자연어 지시·목표 길이도 조건이며 결과의 의미·길이를 보증하는 값은 아닙니다. voice_mode를 생략하면 요청이 쓰는 필드로 정해집니다: 모델의 기본 방식이 그 필드를 모두 받으면 기본 방식, 아니면 그 필드를 모두 받는 방식이 하나뿐일 때 그 방식(예: Ming 3.0에 voice_description만 보내면 voice_design, instructions만 보내면 style)입니다. 저장 보이스(voice:"voice_…")는 언제나 voice_clone입니다. 후보가 없거나 둘 이상이면 기본 방식으로 보고 그 방식의 거절 메시지가 부족한 필드를 알려 줍니다.
| 모델 | 지원 범위 |
|---|
| Qwen3-TTS CustomVoice | 미리 정해진 화자. 공식 1.7B는 자연어 지시·감정/속성 힌트. VoiceDesign과 Base 복제는 별도 체크포인트 설치 필요 |
| Ming3 | 7언어. 다국어 복제는 참조 음성+전사 필수. 디자인·스타일·감정·속성은 영어/중국어만 |
| MOSS-TTS Local v1.5 | 31언어·기본 음성·참조 음성 복제·스타일 지시·목표 길이. VoiceGenerator의 디자인과 다른 모델 |
| Raon 9B /21B-A3B | 한국어/영어·기본 음성·참조 화자 복제·이어 말하기. CC-BY-NC-4.0 비상업용. 21B CPU offload는 처리 속도와 RAM 제약을 확인할 것 |
{"model":"ming3-tts","task":"tts","text":"안녕하세요. 좋은 하루 보내세요.","language":"ko","voice_mode":"voice_clone","reference_audio_base64":"<사용 권한이 있는 참조 음성>","reference_text":"참조 음성의 실제 전사"}
참조 음성은 WAV/MP3/FLAC/OGG/M4A, 최대6MiB·0.1~30초입니다. 비공개 파일 저장소에 보관하고 이력/로그/SQL에는 base64 원문을 남기지 않습니다. 작업 소유권·삭제·입출력 저장 한도를 동일 적용합니다. 모델 전달 시 길이를 제한해 24kHz 모노로 디코딩하고 작업 후 임시 파일을 제거합니다.
POST /v1/audio/speech도 등록된 로컬 모델에는 비동기202를 반환합니다. text 대신 input, response_format:"wav", stream:false를 쓰며 나머지 음성 옵션은 같습니다. 미등록 기존 TTS 서버의 동기 응답과 구분하세요. 모델 내부 스트리밍 기능과 관계없이 현재 로컬 API는 완료된 WAV를 제공합니다.
목소리 계약(voice)과 보이스 라이브러리
한 가지 계약. 모든 음성 합성 모델은 GET /v1/models 항목의 voice 블록(등록 로컬 모델은 GET /v1/media/models·GET /v1/audio/voices?model=에도)에 같은 형식으로 무엇을 할 수 있는지 게시합니다. 네이티브 모델의 tts 블록과 등록 로컬 모델의 speech 블록은 그대로이고, voice는 그 둘을 대신하지 않고 목소리 기능만 같은 모양으로 묶은 것입니다. 없는 기능은 생략하지 않고 unsupported로 적습니다.
"voice": {
"schema_version": 1,
"requires": "design|saved_voice",
"presets": {"status": "available|fixed|on_load|unconditioned|unsupported", "source": "engine|recipe|none", "language_tags": "model_card|none",
"engine_default": "Junhao", "recommended_by_language": {"ko": "sohee"},
"by_language": {"ko": ["sohee"], "en": ["ryan", "aiden"], "*": ["언어 표기가 없는 목소리"]},
"items": [{"id": "sohee", "name": "Sohee", "languages": ["ko"], "description": "…"}]},
"design": {"status": "…", "model_support": "yes|no|other_checkpoint", "adapter_exposed": false, "measured": false,
"fields": ["voice_description"], "languages": ["ko"], "max_chars": 1000, "requires_checkpoint": "…", "note": "…"},
"style": {"…": "design과 같은 모양, fields는 instructions", "input_format": "free_text|native_tags",
"tag_syntax": "<|{value}|>", "supported_values": ["style:whispering"], "measured_values": ["style:whispering"], "min_values": 1, "max_values": 3},
"clone": {"…": "…", "languages": ["ko", "en"], "applies_to": ["S1"],
"reference": {"transcript": "required|optional|unused|unknown", "min_seconds": 1, "max_seconds": 30, "max_bytes": 6291456, "formats": ["wav"], "max_transcript_chars": 1000,
"languages": ["ko", "en", "zh"], "cross_language": "supported|unsupported|unknown", "verified_pairs": ["ko>ko", "ko>en"]}}
}
requires는 요청이 목소리 출처를 하나는 반드시 대야 하는 모델에만 있습니다(없으면 프리셋이나 모델의 자체 선택으로 충분). design은 내장 목소리가 없어 voice_description이 필수이고 voice와 저장 보이스를 받지 않는 모델(예: Qwen3-TTS VoiceDesign — 완성된 WAV만 내며 스트리밍 없음), saved_voice는 내장 목소리도 참조 없는 합성도 없어 voice에 저장 보이스(참조 녹음과 정확한 전사)가 필수인 모델(예: Qwen3-TTS Base)입니다. 둘 다 presets.status는 unsupported이고 출처가 없는 요청은 워커로 보내기 전에 400입니다. 설계 모델이 만든 목소리는 복제 모델이 소비하므로, 보이스 라이브러리가 compatibility로 어느 모델에서 쓸 수 있는지 알려 줍니다.
세 기능은 서로 다른 일입니다. 설계(`design`) 는 자연어 설명(voice_description)으로 새 음색을 만들고, 말투(`style`) 는 이미 있는 목소리에게 어떻게 읽을지 지시(instructions·감정 옵션)하며 누가 읽는지는 바꾸지 않고, 복제(`clone`) 는 참조 녹음으로 목소리를 정합니다. 각 기능의 status는 세 사실에서 정해집니다.
| status | model_support | adapter_exposed | 뜻 |
|---|
available | yes | true | 모델이 하고 이 프로필이 호출을 받으며 실제 장비에서 돌려 봄(measured:true) |
unmeasured | yes | true | 어댑터가 호출을 받지만 아직 아무도 실제 장비에서 돌려 보지 않음(measured:false). 시험할 수 있도록 요청은 받지만 의존하지 마세요 — 실측 뒤에 available이 됩니다 |
not_exposed | yes | false | 모델은 하지만 이 프로필의 어댑터가 아직 받지 않음(note에 무엇이 모자란지) |
needs_checkpoint | other_checkpoint | false | 같은 계열의 다른 체크포인트(requires_checkpoint)가 한다. 예: Qwen3-TTS의 VoiceDesign·Base |
unsupported | no | false | 모델이 못 함 |
`measured:true`는 품질 보증이 아닙니다. 운영 Console을 거쳐 그 요청을 실제로 보냈고 합성음을 다시 전사했을 때 요청한 문장과 맞았다는 기록일 뿐입니다. 화자 유사도, 감정·속도 같은 지시를 얼마나 따르는지, 긴 문장이나 반복·동시 사용에서의 안정성, 목록에 없는 언어 조합은 보증하지 않습니다. 모델마다 알려진 한계(재전사가 틀린 요청이 섞여 있음, 한 번 다른 언어로 읽음, 뒤 문장 누락, 일부 교차 언어 쌍 제외 등)는 해당 기능의 note와 reference.verified_pairs(실제로 맞았던 참조→합성 언어 쌍만)에 적혀 있으니 의존하기 전에 읽으세요.
measured는 실제 장비에서 Console을 거쳐 돌려 봤는지입니다(네이티브 모델은 항상 true/false로 적고, 등록 로컬 모델은 기록이 없어 생략하며 available로 게시). not_exposed·needs_checkpoint·unsupported 기능을 요청하면 릴레이가 워커로 보내기 전에 그 상태를 말하는 400을 돌려줍니다. 프리셋은 로드된 엔진이 보고한 실제 목록(source:"engine", 로드 전에는 레시피의 목록)이며 by_language는 모델 카드가 밝힌 모국어별 분류입니다(그 목소리로 모델의 모든 지원 언어를 합성할 수 있음). engine_default는 voice를 생략할 때 엔진이 쓰는 목소리이고 recommended_by_language는 권장입니다. presets.status:"fixed"는 목소리를 고를 수 없는 모델(voice 생략 또는 default), on_load는 엔진이 로드된 뒤에야 목록을 게시하는 모델(로드 전에는 items가 비어 있음), unconditioned는 내장 목소리가 없고 참조를 주지 않으면 모델이 화자를 매번 정하는 모델(voice 생략 또는 default; 같은 목소리는 저장 보이스로만 보장), unsupported는 내장 목소리가 없는 모델입니다.
말투 입력 형식(`style.input_format`). free_text는 아무 문장이나 받습니다(max_chars 한도). native_tags는 모델 자체의 공식 태그만 받습니다: tag_syntax(예: <|{value}|>)의 {value}를 supported_values 중 하나로 채운 태그를 min_values~max_values개, 중복 없이, 공백 외에는 다른 글자(쉼표 포함) 없이 instructions에 적습니다. 값이 category:value 형태이면(Higgs: emotion:anger·style:whispering·prosody:speed_slow) 태그는 <|emotion:anger|><|style:whispering|>처럼 씁니다. measured_values는 그중 실제 장비에서 돌려 본 값이고 나머지는 모델의 공식 태그라는 사실만 확인된 것입니다(효과는 평가하지 않음). 자유 문장은 엔진이 읽어 버리지 않도록 릴레이가 400으로 거절하며 메시지에 문법과 값을 알려 줍니다. 태그형 말투는 실측하기 전에는 unmeasured이고 화면에서는 태그 버튼으로만 고릅니다.
참조 언어와 합성 언어는 다릅니다. 복제의 languages는 그 목소리로 합성할 수 있는 언어이고, reference.languages는 모델이 참조 녹음으로 받는 언어입니다(없으면 모델 카드가 제한하지 않음). reference.cross_language는 한 언어의 참조로 다른 언어를 합성할 수 있는지입니다: supported(실제 장비에서 확인), unsupported(참조 언어로만 합성), unknown(확인 전). unknown인 모델은 이전 규칙대로 참조 언어도 languages 안이어야 쓸 수 있고, supported면 참조 언어는 reference.languages만 지키면 되어 한국어 녹음으로 영어를 합성할 수 있습니다. reference.verified_pairs(참조>합성, 예 ko>en)는 그중 실제 장비에서 돌려 본 조합이고 reference.languages·languages는 모델 카드가 밝힌 언어라 그보다 넓을 수 있습니다(실측 조합과 카드 기준을 구분해 읽으세요). reference.max_transcript_chars는 모델이 받는 전사 길이이며 더 긴 전사를 가진 보이스는 호환성 목록에서 이유와 함께 제외됩니다. GET /v1/audio/voices의 compatibility[]는 이 계산의 결과로 synthesis_languages(그 보이스로 이 모델이 합성하는 언어)·cross_language·warnings를 담습니다.
clone.applies_to는 복제한 목소리가 출력의 일부만 바꾸는 모델에서 바꾸는 부분을 적습니다(예: 대화 모델 MOSS-TTSD는 ["S1"] — 저장 보이스는 첫 화자 S1만 바꾸고 S2는 모델에 고정된 참조 그대로). compatibility[].applies_to와 warnings에도 같은 사실이 나옵니다.
보이스 라이브러리. 직접 만든 목소리를 저장해 다음 문장에 같은 목소리로 쓰는 기능입니다. 시드나 설명만으로는 같은 화자를 보장하지 않으므로 실제로 재사용할 수 있는 산출물을 저장합니다: 복제는 업로드한 참조 녹음(WAV)과 전사, 설계는 모델이 설명으로 합성한 샘플 WAV와 그 대본입니다. 설계로 만든 보이스를 다시 쓸 때는 그 샘플이 참조로 쓰이므로 복제를 지원하는 모델에서 쓰고, 모델마다 같은 참조라도 소리는 다릅니다. 호출자는 URL이나 서버 경로를 주지 않습니다. 녹음은 업로드로만 들어와 릴레이가 고른 비공개 키에 저장되고, 이후에는 보이스 ID(voice_ + 24자리 16진수)만 씁니다. 보이스는 만든 사람(대시보드 사용자 또는 API 키)만 보고 쓰고 지울 수 있습니다. 읽기는 audio_tts, 만들기·이름 변경·저장·삭제는 audio_voices 범위입니다. 보이스 저장소가 연결되어 있지 않으면 503 FILE_STORE_REQUIRED입니다.
| 요청 | 설명 |
|---|
POST /v1/audio/voices | multipart: name(필수, 60자), language(필수, 참조/샘플의 언어), kind(clone 기본, 파일 없이 description이 있으면 design), model(복제는 선택, 설계는 필수), save(true/false). 복제: file(WAV, PCM 8~32비트·float32, 모노/스테레오, 8~96kHz, 1~30초·6MiB 이하)와 reference_text(전사, 4000자; 모델이 요구하면 필수). 설계: model(설계가 available인 네이티브 모델)·description(1000자)·sample_text(200자)를 주면 릴레이가 그 모델에 한 번 합성시켜 샘플을 저장 |
| 상태 | saved(복제 기본) 또는 draft(설계 기본; 24시간 안에 PATCH {"save":true}로 저장하지 않으면 녹음과 함께 삭제). 저장 보이스는 소유자당 50개, 미리보기는 5개까지(초과 429 VOICE_LIMIT) |
GET /v1/audio/voices | 기존 voices·models·default_voice에 내 보이스 목록 saved가 추가됩니다. ?model=은 모델의 voice 계약과 내 보이스를 돌려줍니다 |
GET /v1/audio/voices/{id} | 보이스 한 개: artifact(형식·길이·샘플레이트·SHA-256), sample_url, 그리고 지금 제공 중인 모든 TTS 모델에 대한 compatibility[{model, compatible, reasons}] |
PATCH · DELETE | 이름 변경·저장 · 삭제(저장된 참조 파일도 지움) |
쓰기. POST /v1/audio/speech의 voice에 보이스 ID를 쓰면 됩니다. 모델의 clone이 available이어야 하고, 릴레이는 호환성을 먼저 검사합니다: 참조 녹음의 언어를 모델이 받는지와 요청 language가 이 보이스로 합성할 수 있는 언어인지(위의 참조 언어·합성 언어 규칙), 참조 길이·크기·형식이 모델의 clone.reference 한도 안인지, 모델이 전사를 요구하면(transcript:"required") 보이스에 전사가 있는지. 어긋나면 이유를 담은 400이고 워커로 보내지 않습니다. 등록 로컬 모델(/v1/audio/speech·/v1/media/jobs)에서는 같은 ID가 기존 voice_clone의 reference_audio_base64·reference_text로 바뀝니다(전사를 쓰지 않는 모델에는 전사를 보내지 않음). 일회성 설계는 voice_description(설계가 available인 모델, voice와 함께 쓸 수 없음), 말투는 instructions를 씁니다. 네이티브 모델에는 참조 녹음을 요청 본문에 직접 담을 수 없습니다(reference_audio_base64·reference_text 400): 먼저 보이스를 만들고 ID를 쓰세요. 말투를 지원하지 않는 모델에 instructions를 보내면 이제 조용히 무시되지 않고 400입니다.
curl "$GPU_CONSOLE_URL/v1/audio/voices" -H "Authorization: Bearer $GPU_CONSOLE_API_KEY" \
-F name="내 목소리" -F language=ko -F reference_text="참조 녹음에서 말한 문장" -F file=@reference.wav
# → {"id":"voice_…","status":"saved","compatibility":[{"model":"…","compatible":true}], …}
curl "$GPU_CONSOLE_URL/v1/audio/speech" -H "Authorization: Bearer $GPU_CONSOLE_API_KEY" -H 'Content-Type: application/json' \
-d '{"model":"<복제가 available인 모델>","input":"다음 문장","language":"ko","voice":"voice_…"}' --output next.wav
현재 Orin 네이티브 모델은 설계·말투·복제를 대부분 not_exposed 또는 needs_checkpoint로 게시합니다(모델 카드 기준 지원이지만 Orin shim이 받지 않거나 별도 체크포인트가 필요). 켜는 방법과 엔진 쪽 요청 필드는 docs/native-engines.md의 엔진 서버 계약을 보세요.
마지막 모델은 API 모드에서 상주합니다. 다른 모델 요청 시 기존 인스턴스를 내린 뒤 교체하며 명시적인 메모리 해제나 API 모드 종료까지 유지합니다. 설치와 API 모드 활성화는 별개이며 GPU별 가용 상태를 확인하세요.
Raon 이어 말하기(continuation)는 선택적으로 reference_text를 받습니다. 전사를 생략하면 내부 STT까지 실행하므로 추가 시간이 걸리며 전사 정확도도 영향을 줍니다. 21B는 BF16 텍스트 backbone을 CPU 오프로딩하고, 직접 파라미터를 참조하는 화자·음성 encoder/codec은 GPU에 유지합니다. 엔진 이미지는 실제 비root 사용자 import로 검사합니다.
다중 이미지·URL 입력과 정확한 크기
모델목록parameters의max_reference_images/reference_inputs/size_policies와파일·픽셀한도를기준으로사용합니다. Qwen2.1/Turbo·FLUX.3은10개, SDXL은1개입니다. images는순서있는배열이며각항목에url또는base64중하나만지정합니다. 단일image_base64도호환되지만images와함께보내지않습니다.
{"model":"qwen-image-21-turbo","task":"i2i","prompt":"색감을 유지하며 배경을 해변으로 변경","images":[{"url":"https://example.com/reference.png"},{"base64":"<이미지 base64>"}],"size_policy":"input_2k","reference_image_index":0}
multipart /v1/images/edits는반복image/image[]파일과반복image_url값을받으며파일다음URL순서입니다. PNG/JPEG/WebP파일당8MiB/8MP·합계24MiB/32MP, 요청본문34MiB까지입니다. source URL은공개HTTP(S)/80·443만지원하고자격·사설주소·메타데이터주소·DNS/리다이렉트우회를거절합니다. 호출자의Cookie/Authorization을전달하지않습니다. 마스크와인증필요원격URL은지원하지않습니다.
size_policy는custom(기존width/height),input_1k(입력비율긴변1024),input_2k(긴변2048),input_original(입력의인코딩픽셀크기)입니다. 기준reference_image_index는0부터/기본0이고입력비율옵션과width/height는같이보내지않습니다. 최종각변8192/8MP안에서모델격자·생성한도로생성한뒤Lanczos비율유지리사이즈/중앙크롭합니다. render_width/height·generated_width/height·postprocess로실제과정을확인하며2K선택을native2K보장으로해석하지않습니다.
원본입력과결과는private SeaweedFS에저장합니다. 응답input_images[].file_url과file_url은API origin기준주소이며기존정상자격으로조회합니다. 익명공개버킷링크가아닙니다. SQL과요청로그에는원본이미지/base64/URL쿼리를저장하지않고키·SHA·크기·출처종류만남깁니다. 삭제시입력/출력모두제거합니다. 같은소유자·Idempotency-Key·본문의재확인은이전스냅샷/작업ID를반환하고URL을다시받지않습니다.
확장옵션은gpu-media-image-inputs-v1실행기가필요하며구실행컨테이너는갱신필요오류로거절합니다. 진행작업을마친뒤API모드종료→실행환경준비→API모드켜기순서로갱신합니다. 다운로드/모드전환과생성성공을구분하고불명작업을자동재생성하지마세요.
전체 엔드포인트 목록
아래의 세션은 승인된 대시보드 로그인, 관리자는 관리자 세션을 뜻합니다. 내부 워커 터널도 포함하며 외부 추론 키로 관리·장비 인증을 수행하지 않습니다. 경로 변수는 URL 인코딩하세요.
리소스 모니터
| 메서드 | 경로 | 인증 | 내용 |
|---|
| GET | /telemetry/status | 관리자 | 최신 PC/GPU 지표·수집 설정·저장 용량/건수/정리 상태 |
| GET | /telemetry/history | 관리자 | 시계열; worker_id/since/until/limit |
| GET | /telemetry/events | 관리자 | 관측 이벤트; worker_id/since/until/limit |
| PUT | /telemetry/config | 관리자 | 전체 수집·보관 설정 저장 |
| GET | /telemetry/preferences | 관리자 | 본인 그래프 지표 목록 조회/저장; metrics 배열 |
| PUT | /telemetry/preferences | 관리자 | 본인 그래프 지표 목록 조회/저장; metrics 배열 |
진단·계정
| 메서드 | 경로 | 인증 | 내용 |
|---|
| GET | / | 공개 | 대시보드 HTML |
| GET | /dashboard | 공개 | 대시보드 HTML; no-store |
| GET | /dashboard-assets/{file} | 공개 | 내용 해시별 정적 JS/CSS; immutable 캐시, 계정 데이터 없음 |
| GET | /llms.txt | 공개 | LLM용 문서 색인; text/plain |
| GET | /llms-full.txt | 공개 | 전체 Markdown API 원문; text/plain |
| GET | /healthz | 공개 | 프로세스 상태·워커 수 (모델 실행 판정 아님) |
| GET | /readyz | 공개 | 저장소 연결·단일 writer 임대 확인; DB 장애 시 503, liveness와 분리 |
| POST | /operator/attachments/legacy/prune | 관리자 | SeaweedFS 전송·암호화 파일 백업 확인 후 지정 ID의 구 SQL 파일 본문만 정리 |
| GET | /auth/me | 공개 | 현재 로그인 상태·사용자 |
| POST | /auth/register | 공개 | 가입 신청; login_id/password |
| POST | /auth/login | 공개 | 로그인; login_id/password → 세션 쿠키 |
| POST | /auth/admin-sso/ticket | 전용 서비스 토큰 | Taek Admin 서버 전용; 30초·1회용 로그인 코드 발급. Relay API 키로 호출 불가 |
| POST | /auth/admin-sso | 1회용 코드 + 고정 Admin Origin | Taek Admin의 폼 POST로 기존 관리자 세션 발급 후 /dashboard 이동. 미구성·만료·재사용 거부 |
| POST | /auth/logout | 세션 | 현재 세션 로그아웃 |
| POST | /auth/password | 세션 | 현재·새 비밀번호 변경; current_password/new_password |
| GET | /admin/users | 관리자 | 사용자 목록 |
| POST | /admin/users/{user_id}/approve | 관리자 | 가입 승인 |
| POST | /admin/users/{user_id}/disable | 관리자 | 사용 중지 |
| POST | /admin/users/{user_id}/enable | 관리자 | 사용 재개 |
| DELETE | /admin/users/{user_id} | 관리자 | 사용자 삭제 |
| GET | /status | 세션 | GPU·대기열·서킷·진행 중 요청 |
| GET | /workers | 세션 | 워커 목록·기능·버전 |
| GET | /requests | 세션 | 요청 이력; limit/offset/from/to/provider/gpu/worker_id/model/status/api_key |
| GET | /stats/summary | 세션 | 집계; 이력과 같은 필터 |
별도 워커·통합
| 메서드 | 경로 | 인증 | 내용 |
|---|
| GET | /worker/ws | 장비 자격 / 기존 워커 토큰 | 추론·운영·자원 터널; 신규 장비는 코드 승인, 토큰 없는 기존 연결은 등록된 GPU ID만 허용 |
| GET | /worker/install.sh | 공개 | Linux 설치 시작 스크립트 |
| GET | /worker/setup.mjs | 공개 | 설치 클라이언트; 승인 전 워커 소스는 제공하지 않음 |
| POST | /worker/pairing/start | 공개·제한 | hostname/platform/arch → 일회용 code/id/ticket,10분. 기존 PC 이관은 existing_worker_id 명시 |
| GET | /worker/migration/status | 이관 PC 자격 | 자신의 prepared/active 상태와 새 워커 시작 시각 조회 |
| POST | /worker/migration/commit | 이관 PC 자격 | 새 설치형 워커 접속 확인 후 동일 ID 이관 확정. 재시도 가능 |
| POST | /worker/migration/rollback | 이관 PC 자격 | 확정 전 새 자격 취소·기존 연결 복구 허용. 확정 후 되돌리기 불가 |
| POST | /worker/pairing/poll | 일회용 ticket | id/ticket →202 pending 또는 승인된 worker_id/token, ack:true로 pending 정리 |
| POST | /worker/media-upload/{id}/{artifact} | 작업별 임시 전송 자격 | 실행기 전용8MiB 분할 전송; API 키·일반 브라우저 접근 불가 |
| GET | /worker/setup/config | 장비 자격 | worker_id·자동 LAN TLS 접속 설정·공개 CA |
| POST | /worker/update/{id} | 장비 자격 | 승인된 한 PC 실행기 갱신의 유휴 재검사·재연결·복구 보고. 명령 재실행·장비 재등록 없음 |
| GET | /worker/setup/manifest | 장비 자격 | private bundle SHA256·크기·경로·설치기 SHA256 |
| GET | /worker/setup/bundle | 장비 자격 | allowlist로 묶은 워커/operator 소스·lockfile |
| GET | /admin/worker-pairing | 관리자 세션 | 설치형 장비·서비스 연결 목록 |
| POST | /admin/worker-pairing/preview | 관리자 세션 | code → 승인 대기 PC 정보 |
| POST | /admin/worker-pairing/approve | 관리자 세션 | code/name/bindings:[{service,id}] → 장비 승인, 명시적 서비스 묶음 |
| POST | /admin/worker-pairing/revoke | 관리자 세션 | id → 관리 연결 즉시 해제; 모델/전용 서비스는 유지 |
| GET | /tribe/worker/ws | TRIBE 토큰 (설정 시) | TRIBE 전용 터널 |
| GET | /tribe/workers | TRIBE 토큰 (설정 시) | TRIBE 워커 목록 |
| POST | /tribe/dispatch | TRIBE 토큰 (설정 시) | TRIBE 작업 실행 |
| GET | /bgremove/worker/ws | 배경 제거 토큰 | 배경 제거 전용 터널; BGREMOVE_RELAY_TOKEN |
| GET | /bgremove/workers | bgremove 키 / 세션 / 배경 제거 토큰 | 배경 제거 워커 목록 |
| POST | /bgremove/v1/remove-background | bgremove / 세션 | multipart image 배경 제거 |
키·라우팅
| 메서드 | 경로 | 인증 | 내용 |
|---|
| GET | /api-keys | 관리자 | 비밀값을 제외한 키·정책 목록 |
| GET | /api-keys/scopes | 관리자 | 정의된 scope 목록 |
| POST | /api-keys | 관리자 | 키 생성; secret은 생성 응답에서 한 번만 반환 |
| PATCH | /api-keys/{key_id} | 관리자 | 이름·scopes·우선순위·native 동시성 부분 편집; 비밀값 유지 |
| GET | /routing/messages-key-defaults | 관리자 | 새 Messages 키 초기 제안 조회 |
| PUT | /routing/messages-key-defaults | 관리자 | 새 키 초기 제안 저장; 기존 키는 유지 |
| DELETE | /api-keys/{key_id} | 관리자 | 키 폐기 |
| GET | /routing/config | 세션 | 라우팅·큐 설정 조회 |
| PUT | /routing/config | 관리자 | 라우팅·큐 설정 저장 |
GPU·기존 모델 제어
| 메서드 | 경로 | 인증 | 내용 |
|---|
| PUT | /workers/{worker_id}/max-concurrency | 관리자 | 워커 동시성 override; max_concurrency |
| DELETE | /workers/{worker_id}/max-concurrency | 관리자 | 동시성 override 제거 |
| POST | /workers/{worker_id}/update | 관리자 | 워커 코드 갱신; force 기본 false, 작업 결과 확인 후 재요청 판단 |
| GET | /gpu-slots | 세션 | 오프라인 포함 고정 GPU 번호·connected·display_name·hostname·device_id 목록 |
| PUT | /gpu-slots/{worker_id} | 관리자 | 슬롯 번호 지정; gpu_index. 온라인·오프라인 장비가 점유한 다른 번호는409 gpu_slot_occupied(소유 장비 안내, 변경 없음). 교환은 POST /gpu-slots/swap 사용. 이전 중복 슬롯 정리는 같은 번호와 reconcile_previous_ids(정확한 오프라인 후보 ID 목록)를 명시하며 현재 연결 장비만 소유자로 확정 |
| PUT | /gpu-slots/{worker_id}/name | 관리자 | 지정 이름 저장; name(100자 이내, 빈 값은 기본 표시), expected_name(이전 저장값, 동시 수정 시409). 인증·라우팅 불변 |
| PUT | /gpu-slots/{worker_id}/failover | 관리자 | 슬롯 failover; enabled |
| PUT | /gpu-slots/{worker_id}/disabled | 관리자 | 신규 라우팅 보류/재개; disabled (모델 중지 아님) |
| POST | /gpu-slots/swap | 관리자 | 슬롯 교환; left/right (GPU 번호) |
| GET | /model-aliases | 관리자 | 모델 별칭 목록·현재 해석·최근 24시간 요청 수·삭제된 별칭 |
| POST | /model-aliases | 관리자 | 별칭 생성; name/kind/items/wait_ms |
| GET | /model-aliases/{name} | 관리자 | 별칭 하나 |
| PATCH | /model-aliases/{name} | 관리자 | 이름·종류·대기 한도·목록 변경; version 필수(낙관적 잠금) |
| DELETE | /model-aliases/{name} | 관리자 | 별칭 삭제; ?version= 필수 |
| PUT | /model-aliases/{name}/items | 관리자 | 순서 있는 모델 목록 전체 교체; items/version |
| GET | /model-aliases/{name}/history | 관리자 | 변경 이력(누가·언제·이전→이후) |
| POST | /model-aliases/{name}/revert | 관리자 | 한 변경 이전 상태로 되돌리기; seq/version |
| GET | /model-aliases/{name}/resolve | 관리자 | 저장된 별칭이 지금 어느 모델·GPU로 해석되는지 |
| POST | /model-aliases/{name}/resolve | 관리자 | 저장하지 않은 목록(items/kind/wait_ms)의 해석 미리보기 |
| GET | /models/catalog | 관리자 | 모델 선택기용: 광고 중·이전에 올라온 모델, 종류, 올라온 GPU, 컨텍스트, 비전 |
| PUT | /models/kind | 관리자 | 모델 종류 수정(빈 kind면 수정 취소); model/kind |
| GET | /workers/{worker_id}/lmstudio/models | 세션 | 워커 백엔드 모델 조회; vLLM·OpenAI 호환은 실행 모델만 |
| POST | /workers/{worker_id}/lmstudio/models/load | 관리자 | LM Studio 모델 로드; vLLM 관리의 대체 경로 아님 |
| POST | /workers/{worker_id}/lmstudio/models/unload | 관리자 | LM Studio 모델 해제 |
| POST | /workers/{worker_id}/lmstudio/models/download | 관리자 | LM Studio 다운로드 시작 |
| GET | /workers/{worker_id}/lmstudio/models/download/status/{job_id} | 세션 | LM Studio 다운로드 진행 조회 |
| GET | /workers/{worker_id}/sampling | 관리자 | GPU·모델별 샘플링 기본값 조회; model 쿼리 필수 |
| PUT | /workers/{worker_id}/sampling | 관리자 | 독립 기본값 저장; model/enabled/sampling_defaults/source/checked_at |
| PUT | /workers/{worker_id}/lmstudio/model-settings | 관리자 | 기본 temperature 저장; instance_id/default_temperature |
| GET | /huggingface/models | 세션 | Hugging Face 검색; q 필수, limit 1–50 (기본12) |
로컬 도구 루프 관리
| 메서드 | 경로 | 인증 | 내용 |
|---|
| POST | /agent/chat | agent / 세션 | 로컬 GPU 모델 도구 루프 (운영 어시스턴트와 별개) |
| GET | /agent/tools | 세션 | 활성 에이전트 도구 목록 |
| POST | /agent/tools | 관리자 | 도구 생성 |
| POST | /agent/tools/test | 관리자 | 도구 실행 테스트 (부작용 가능) |
| POST | /agent/tools/generate | 관리자 | 모델로 도구 정의 생성 |
| PUT | /agent/tools/{tool_id} | 관리자 | 도구 수정 |
| DELETE | /agent/tools/{tool_id} | 관리자 | 도구 삭제 |
| PUT | /agent/builtins/{name} | 관리자 | 내장 도구 사용 설정 |
| GET | /agent/mcp-servers | 관리자 | MCP 서버 목록; 비밀 필드는 마스킹 |
| POST | /agent/mcp-servers | 세션 | MCP 서버 생성 |
| PUT | /agent/mcp-servers/{server_id} | 세션 | MCP 서버 수정 |
| DELETE | /agent/mcp-servers/{server_id} | 세션 | MCP 서버 삭제 |
| POST | /agent/mcp-servers/{server_id}/refresh | 세션 | MCP 도구 목록 다시 가져오기 |
추론
| 메서드 | 경로 | 인증 | 내용 |
|---|
| GET | /v1/models | 모든 범위의 키 / 세션 | 가용 모델·GPU 별칭·capabilities |
| POST | /v1/chat/completions | chat / 세션 | OpenAI 채팅/스트리밍 |
| POST | /v1/messages | messages / 세션 | Anthropic native 생성 또는 토큰 수 |
| POST | /v1/messages/count_tokens | messages / 세션 | Anthropic native 생성 또는 토큰 수 |
| POST | /v1/audio/transcriptions | audio_stt / 세션 | multipart file → STT |
| POST | /v1/audio/translations | audio_stt / 세션 | multipart file → STT + LLM 번역 (확장 JSON) |
| POST | /v1/audio/speech | audio_tts / 세션 | 기존 서버: 오디오 바이트 / 등록 로컬 모델: 비동기202 |
| GET | /v1/audio/voices | audio_tts / 세션 | voices/models/default_voice |
| POST | /v1/audio/voices | audio_voices / 세션 | 내 보이스 만들기: multipart file(WAV 참조)+name·language·reference_text, 또는 kind:design(설명으로 설계) |
| GET | /v1/audio/voices/{id} | audio_tts / 세션 | 내 보이스 한 개와 모델별 호환성 |
| PATCH | /v1/audio/voices/{id} | audio_voices / 세션 | 이름 변경, 미리보기 보이스 저장(save:true) |
| DELETE | /v1/audio/voices/{id} | audio_voices / 세션 | 보이스와 저장된 참조 음성 삭제 |
| GET | /v1/audio/voices/{id}/sample | audio_tts / 세션 | 저장된 참조/샘플 WAV 재생 |
| POST | /v1/audio/alignments | audio_align / 세션 | multipart file + text → 어절별 시작·끝(초). 전사가 아닌 정렬 |
운영 어시스턴트 (Codex·Claude)
| 메서드 | 경로 | 인증 | 내용 |
|---|
| GET | /operator/devices | 관리자 + 소유자 경계 | 장비·설치/구독 인증 상태 |
| GET | /operator/devices/{device_id}/models | 관리자 + 소유자 경계 | 엔진 모델 목록; provider=codex 또는 claude |
| POST | /operator/devices/{device_id}/auth | 관리자 + 소유자 경계 | Claude 장비 인증; provider/method(token,local,clear)/value |
| GET | /operator/devices/{device_id}/codex-auth | 관리자 + 소유자 경계 | Codex 장비 계정·진행 중 로그인 상태 (토큰 제외) |
| POST | /operator/devices/{device_id}/codex-auth/start | 관리자 + 소유자 경계 | 선택 장비에서 독립 일회용 코드 로그인 시작 |
| POST | /operator/devices/{device_id}/codex-auth/cancel | 관리자 + 소유자 경계 | 자신이 시작한 로그인 취소; login_id |
| POST | /operator/devices/{device_id}/codex-auth/logout | 관리자 + 소유자 경계 | 선택 장비 연결 해제; 진행 중 작업이면 거절 |
| GET | /operator/devices/{device_id}/huggingface | 관리자 + 소유자/PC 경계 | HF 토큰 등록 여부·계정·도구 상태; 토큰 제외 |
| PUT | /operator/devices/{device_id}/huggingface | 관리자 + 소유자/PC 경계 | token을 HF에서 검증 후 암호화 저장; no-store |
| DELETE | /operator/devices/{device_id}/huggingface | 관리자 + 소유자/PC 경계 | 내 토큰 연결 해제; 진행 중 다운로드는409 |
| GET | /operator/providers | 관리자 + 소유자 경계 | 호환용 서버 API 계정 상태; 새 장비 구독과 별개 |
| GET | /operator/accounts/{provider} | 관리자 + 소유자 경계 | 호환용 API 계정 모델 조회 |
| PUT | /operator/accounts/{provider} | 관리자 + 소유자 경계 | 호환용 API 계정 저장; api_key (별도 API 과금) |
| DELETE | /operator/accounts/{provider} | 관리자 + 소유자 경계 | 호환용 API 계정 삭제 |
| GET | /operator/sessions | 관리자 + 소유자 경계 | 소유자의 대화 목록 |
| POST | /operator/sessions | 관리자 + 소유자 경계 | 대화 생성; provider/model/device_id/worker_id/reasoning/thinking/permission_mode |
| GET | /operator/sessions/{session_id} | 관리자 + 소유자 경계 | 대화·저장 이벤트 조회 |
| PUT | /operator/sessions/{session_id}/settings | 관리자 + 소유자 경계 | reasoning/thinking/permission_mode 변경; 진행 중이면409 |
| POST | /operator/sessions/{session_id}/turn | 관리자 + 소유자 경계 | prompt 최대32,000 bytes; 202 run |
| GET | /operator/sessions/{session_id}/delegations | 관리자 + 소유자 경계 | 자식 위임 실행 조회 |
| POST | /operator/sessions/{session_id}/delegate | 관리자 + 소유자 경계 | 다른 장비에 위임; device_id/provider/model/prompt |
| GET | /operator/runs | 관리자 + 소유자 경계 | 소유자의 실행 목록 |
| POST | /operator/runs/{run_id}/interrupt | 관리자 + 소유자 경계 | 실행 중단 요청; 202 |
| GET | /operator/runs/{run_id}/events | 관리자 + 소유자 경계 | SSE; Last-Event-ID 또는 after로 이어받기 |
| GET | /operator/jobs | 관리자 + 소유자 경계 | 작업 이력; view=summary로 최근 목록·커서 조회, 전체 결과는 개별 상세 |
| POST | /operator/jobs | 관리자 + 소유자 경계 | 작업 계획 생성; worker_id/profile_id 또는 profile/operation |
| POST | /operator/jobs/{job_id}/approve | 관리자 + 소유자 경계 | 승인 후 실행 또는 PC별 queued 대기; 선행 성공 후 자동 실행, 202 (완료 아님) |
| POST | /operator/jobs/{job_id}/reject | 관리자 + 소유자 경계 | 승인 대기 거절 또는 queued 작업 취소; 이미 실행/처리되면409 |
| GET | /operator/profiles | 관리자 + 소유자 경계 | 소유자의 GPU 실행 프로필 목록; 기존 항목도 version 1로 읽음 |
| POST | /operator/profiles | 관리자 + 소유자 경계 | 실행 프로필 등록; 저장만 수행 |
| GET | /operator/profiles/{id} | 관리자 + 소유자 경계 | 실행 프로필 상세 |
| PUT | /operator/profiles/{id} | 관리자 + 소유자 경계 | 전체 실행 설정과 version으로 수정; 충돌409 |
| DELETE | /operator/profiles/{id} | 관리자 + 소유자 경계 | 본문 version으로 프로필만 삭제; 모델 파일·컨테이너·작업 이력 보존 |
| POST | /operator/tools | 관리자 + 소유자 경계 | gpu_operation: GPU/프로필·위임·PC 명령/파일/이미지/결과파일/작업중지 및 kb_* |
| GET | /operator/kb | 관리자 + 소유자 경계 | 공유 공통/GPU별 트리; q 검색, worker_id, archived |
| POST | /operator/kb | 관리자 + 소유자 경계 | 문서 생성; title/markdown/parent_id/worker_id |
| GET | /operator/kb/{page_id} | 관리자 + 소유자 경계 | 문서 읽기 |
| PATCH | /operator/kb/{page_id} | 관리자 + 소유자 경계 | 문서 교체; version 충돌 시409 |
| GET | /operator/kb/{page_id}/history | 관리자 + 소유자 경계 | 문서 버전 목록 |
| POST | /operator/kb/{page_id}/restore | 관리자 + 소유자 경계 | revision 복원; 현재 version 필요 |
| POST | /operator/kb/{page_id}/archive | 관리자 + 소유자 경계 | 보관/해제; archived와 현재 version |
작업 목록의 권장 조회는 GET /operator/jobs?view=summary&limit=30&include_active=1이다. limit은1~100(기본30), cursor는 이전 응답의 next_cursor를 그대로 사용한다. has_more가 true인 동안 이어 읽는다. worker_id 또는 session_id(동시 지정 불가), state로 범위를 제한할 수 있으며 커서는 같은 범위에서만 유효하다. include_active=1은 첫 페이지에 오래된 awaiting_approval/queued/running 작업도 추가하므로 items 수가 limit보다 클 수 있다. 요약은 stdout/stderr/logs/output/events를 생략하고 has_details:true를 반환하며, 실행 설정과 복구·정리·진행 상태는 유지한다. GET /operator/jobs/{id}에서 같은 소유자만 원본 전체 결과를 읽는다. category=comfy 또는 category=media는 해당 관리 화면의 상태 스냅샷으로, 과거 복구·정리 경고를 보존하기 위해 그 종류의 요약 전체를 반환하고 커서를 받지 않는다. 쿼리 없는 호환 목록은 기존 전체 원본 응답을 유지한다.
생성 이미지 관리
GPU Console의 사용 이력 → 생성 이미지에서 로컬 GPU와 Codex의 결과를 모아 보고 이미지 파일만 삭제할 수 있습니다. 파일 삭제는 저장소의 결과 본문을 제거하며 생성 상태·프롬프트·입력 파일·이력은 유지합니다. 삭제된 결과의 파일 조회는410을 반환하고 상태에는 output_deleted_at을 표시합니다. 삭제 확인 중에는 파일 주소를 제공하지 않습니다. 현재 이미지 출력은32MiB 이하이며 입력 이미지8MiB/전체24MiB·음성 입력12MiB 제한과 모델의 해상도 제한은 별개입니다. 큰 영상 전송과 Range 재생은 아직 제공하지 않습니다.
로컬 영상 API와 실행 상태
ComfyUI 영상은 videos 범위 키로 기존 POST /v1/media/jobs에 task:t2v 또는 task:i2v와 등록 모델 ID를 보냅니다. 모델별 workflows[].video에 기본 width/height/frames/fps, 해상도 단위·프레임 격자·FPS 범위·오디오·참조 수가 있습니다. I2V의 images는 이미지 API와 같이 공개 URL 또는 base64 입력을 받으며 로그/DB에는 본문을 남기지 않습니다. 각 워크플로가 지원하는 입력 수만 받으며 첫/끝 프레임과 다중 인물 참조를 같은 기능으로 가정하지 않습니다.
프레임 수는 frames, 속도는 fps로 지정합니다. duration_seconds를 함께 지정하면 frames == duration_seconds * fps여야 합니다. 격자에서 벗어난 값을 조용히 반올림하지 않습니다. workflow와 workflow_version, LoRA·샘플링 옵션은 등록 바인딩이 지원하는 범위에서만 사용합니다.
영상은 MP4(H.264, 생성 오디오는 지원 코덱으로 보존)와 대표 PNG를 반환합니다. 상태의 file_url, poster_url은 기본 공개·무제한이며 authenticated_file_url, authenticated_poster_url은 소유자/관리자 경로입니다. 비공개·기간 공개/해제는 이미지와 같은 share API와 갤러리에서 설정하며 입력은 비공개입니다. 파일 조회는 Range·HEAD 재생을 지원합니다. 관리자 video_max_mib 설정은 기본512MiB·1~2048MiB이며 새 접수부터 반영하고 기존 접수의 한도는 유지합니다. 생성 이후 전송 오류는 업로드만 재시도합니다.
이미지(Codex 포함)·영상의 생성 접수202와 작업 조회 응답은 모두 scheduling을 반환합니다. availability.ready는 실행기 준비 상태, can_start_now는 조회 시점 즉시 실행 가능성, waiting_reason은 준비/앞선 작업/동시성/Comfy 큐 대기 이유입니다. queue.position은 실행 중0·대기1부터·종료null, ahead는 앞선 작업 수이며 대상 GPU 또는 Codex CLI 풀 단위입니다. 개인정보 없이 건수만 제공하며 외부 Comfy 큐·재접속·전역 동시성 때문에 순번은 스냅샷 추정값(position_is_estimate:true)입니다. sampled_at으로 신선도를 확인하세요.
model_loading.state는 hot(관측한 파이프라인 모델 전부 GPU 상주), warm(메모리 캐시가 있지만 재로드/오프로딩 필요), cold(관측 모델 캐시 없음), loading(실제 모델 적재 중), unknown(확인 불가)입니다. Comfy 제어 확장3 이상의 런타임 관측을 사용하며 이 정보만으로 생성 속도를 보장하지 않습니다. Codex 상위 이미지 모델의 캐시 상태는 조회할 수 없어 unknown/provider_managed이고 CLI 풀 준비 상태는 별도 executor에 제공합니다. processing.phase와 샘플링 value/maximum은 실제 관측된 경우에만 반환합니다.
고정 vLLM 실행 설정
검증한 로컬 HF 스냅샷을 읽기 전용으로 마운트한 기존 vLLM 컨테이너는 PC 조회의 execution 지문을 실행 프로필에 가져올 수 있습니다. backend: vllm, existing: true이며 gpu-vllm-recipe-v1 실행기가 필요합니다. 원래 컨테이너·이미지·전체 실행 옵션을 검증하고 같은 컨테이너를 시작·중지합니다. 다른 엔진이 실행 중이면 먼저 명시적으로 내리세요. 등록만으로 현재 모델이 바뀌지 않습니다. 가중치는 HF 도구로 준비하며, 레시피가 바뀌면 다시 가져옵니다.
Strata 대시보드 · Console 로그인
이 연결은 설치 코드 방식 PC의 로컬 Strata UI만 제공합니다. 브라우저에 모델 API 키를 전달하지 않습니다. 도메인 연결은 15분 유효 검토와 기존 작업 승인 API를 사용하며, 다른 PC의 DNS·Access·ComfyUI·Studio 주소를 덮어쓰지 않습니다. 도메인 변경은 현재 연결 해제 후 새 주소 연결 순서입니다. 해제 시 접속 세션도 폐기합니다. 전용 Cloudflare 터널은 이후 재연결을 위해 보존합니다.
| 메서드 | 경로 | 인증 | 설명 |
|---|
| GET | /operator/strata-dashboard | 관리자 | worker_id로 PC 상태·현재 주소·검토 지문 조회 |
| POST | /operator/strata-dashboard | 관리자 | worker_id, hostname, expected_version, binding_version, remove로 승인 대기 작업 생성. 모델 재시작 없음 |
| GET | /operator/jobs/{id} | 관리자 + 소유자 경계 | 연결·해제 작업의 상태와 결과 조회 |
| GET | /strata-dashboard/open | Console 관리자 세션 | worker_id의 등록된 주소를 새 탭으로 열기. 미로그인 시 Console 로그인 |
| GET | /strata-dashboard/login | Console 관리자 세션 + PC 호스트 nonce | 60초·1회용·PC/주소/nonce에 묶인 로그인 코드 발급. 외부 redirect 주소 입력 불가 |
| POST | /worker/strata-dashboard/auth | 해당 PC의 장비 자격 | exchange/inspect. 호스트 전용 HttpOnly 세션 발급·실시간 부모 Console 세션 검사. 최대 8시간 |
| POST | /worker/strata-dashboard/chat | 해당 PC의 장비 자격 + 대시보드 세션 | Strata 대화 JSON/SSE를 해당 GPU의 Console 대기열·샘플링·요청 이력으로 처리. 다른 GPU 전환 금지 |
직접 주소로 접속해도 Console 인증이 필요합니다. Console 로그아웃·계정 비활성화·관리자 권한 해제·주소 연결 해제는 대시보드의 다음 요청부터 적용됩니다. 네이티브 모델 로드·해제, 공통 설정·MCP·이미지 생성은 이 프록시에서 실행하지 않고 Console 관리 화면을 사용합니다. 대화 내용의 브라우저 보관은 Strata UI 자체 기능이며 Console 대화 기록과 별개입니다. 모델이 정지됐을 때 접속 버튼으로 자동 기동하지 않습니다.