소비자용 애플리케이션은 기능을 영감의 원천으로 삼을 수는 있지만, 기술적 의존성이 될 필요는 없습니다. 만약 이미지 시나리오 계획에 "이미지를 가져오기 위해 Shedevrum을 호출한다"라는 문구가 등장했다면, 이를 재현 불가능한 호출 방식인 백엔드 계약 (backend-contract)으로 만들기 전에 삭제해야 합니다.

팀이 이곳에 온 이유인 질문에 대한 짧은 답변은 다음과 같습니다: Shedevrum 자체에는 문서화된 API가 없습니다. Yandex 공식 지원 페이지는 2026-07-18 기준으로 Shedevrum을 최종 제품(설치, 사용, 이미지, 비디오 및 텍스트 생성)으로만 설명하며, 개발자를 위한 프로그래밍 방식의 액세스나 통합에 대한 언급은 전혀 포함되어 있지 않습니다. 이는 검색의 누락이 아니라, 존재하지 않는다는 것이 확인된 사실입니다.

이후의 모든 기사는 이 사실을 막다른 길이 아닌 아키텍처 결정으로 만드는 방법에 관한 것입니다. 우리는 사용자 결과물을 필수적인 백엔드 속성 (backend-property)까지 추적하고, 이를 실제로 문서화된 인터페이스와 대조하여 세 가지 중 하나를 얻게 될 것입니다: 의존성을 유지하거나, 교체하거나, 또는 제외하는 것입니다. 만약 명확하게 정의된 모델 단계에 단순히 확인된 API 경로가 필요한 것이라면, 그것은 Yandex의 클라우드 인터페이스이거나, 일부 시나리오의 경우 다른 문서화된 경로가 될 수 있습니다. 이는 별도의 액세스 경로이지, Shedevrum을 백엔드 컴포넌트 (backend-component)로 변환하는 것이 아닙니다.

"Shedevrum에 API가 있는가"라는 질문이 잘못된 이유는 무엇인가?

팀이 디자인 리뷰 (design-review)에 가져오는 논쟁적인 기본 설정은 다음과 같습니다: 소비자용 이미지 애플리케이션을 백엔드 컴포넌트로 간주하는 것입니다. 누군가가 데모에서 Shedevrum으로 만든 아름다운 이미지를 보여주었고, 요구 사항은 "Shedevrum 통합"으로 기록되었으며, 이제 아키텍처는 계약 (contract)이 없는 인터페이스 위에 위태롭게 서 있습니다.

첫 번째 질문은 다르게 던져져야 합니다. 이 기능이 백엔드(backend)로부터 제공받아야 하는 검증 가능한 속성은 무엇인가? 사용자에게는 어떤 서비스가 이미지를 그렸는지는 중요하지 않습니다. 하지만 제품(product)에게는 중요합니다. 제품에는 엔드포인트(endpoint), 인증(authentication), 예측 가능한 응답 형식, 그리고 상업적 이용 권한이 필요합니다. App Store에 있는 애플리케이션은 이 중 그 어떤 속성도 보장하지 않습니다.

여기서 라이선스 계약은 엄격한 경계선을 긋습니다. Shedevrum 모바일 계약은 프로그램의 사용을 개인적인 비영리 목적("for personal non-profit purposes")으로 직접 제한하며, 개발자를 위한 API 또는 통합 권리에 관한 조항을 포함하지 않고, Yandex의 서면 동의 없이 역컴파일(decompilation) 및 파생 제품을 만드는 것을 금지합니다. 애플리케이션 인터페이스를 기술적으로 우회하는 것은 회색 지대를 만드는 것이 아니라 이러한 조건을 위반하는 것이며, 이를 프로덕션(production)의 기반으로 삼을 수 없습니다.

따라서 "api shedevrum"이라는 검색어에 대한 문서화된 답변은 단 하나뿐이며, 그것은 부정적입니다. 즉, 애플리케이션의 소프트웨어 경계(software perimeter)는 존재하지 않습니다. 이는 기능에 대한 약속이 아니라 백로그(backlog)를 위한 테스트 입력값으로 유지되어야 합니다. 이러한 형식의 모든 요청은 누군가의 데모 기억이 아니라 서피스(surface) 상태 확인에 근거해야 합니다.

Yandex가 실제로 공개한 것은 무엇인가?

가장 자주 혼동되는 중요한 갈림길이 있습니다. Shedevrum의 기반이 되는 신경망 YandexART는 Yandex Cloud Foundation Models 클라우드 서비스의 별도 API로 Yandex에 의해 공식적으로 공개되었습니다. Habr의 기업 블로그에는 해당 모델이 "Shedevrum 애플리케이션의 기반이 된다"라고 명시되어 있습니다. 즉, Shedevrum과 YandexART API는 동일한 모델 계층(model layer)에 속하지만, 서로 다른 서피스(surface)이며 동일한 것이 아닙니다.

소프트웨어적 루프(Software loop)는 바로 두 번째 서피스(surface)에 존재합니다. Yandex Cloud / AI Studio 문서에 따르면, YandexART 호출은 art://<folder_ID>/yandex-art/latest 형식의 modelUri를 지정하여 foundationModels/v1/imageGenerationAsync 엔드포인트(endpoint)로 보내는 POST 요청으로 구성됩니다. 계약(contract)의 형태만 보더라도 Yandex Cloud의 폴더 ID(folder ID)가 필요함을 알 수 있는데, 일반 소비자용 애플리케이션에는 이러한 폴더 ID가 존재하지 않습니다. Yandex Cloud 공식 SDK (yandex-ai-studio-sdk) 또한 이를 확인해 줍니다. YandexART와 프로그래밍 방식으로 상호작용하려면 인증(API 키, IAM 토큰, OAuth 토큰 또는 CLI)과 폴더 ID 지정이 필수적입니다.

이 계약은 공식 문서 외의 다른 곳에서도 독립적으로 확인됩니다. Habr의 실무 분석에서도 동일한 아키텍처 세부 사항을 설명합니다: 엔드포인트 llm.api.cloud.yandex.net/foundationModels/v1/imageGenerationAsync, 필수 헤더(header) Authorization: Api-key <key>, 그리고 "생성 요청 후 작업 상태를 폴링(polling)하는" 비동기 패턴입니다. 하나의 계약으로 수렴하는 두 개의 독립적인 출처는, 우리가 특정 문서의 오타에 의존하고 있을 위험을 낮춰줍니다.

요구사항 추적(trace)은 어떻게 이루어지는가?

이제 이 글의 저자가 만든 도구인 requirements-trace를 살펴보겠습니다. 아이디어는 간단합니다. "Shedevrum이 필요하다"라는 모든 문장을 다섯 개의 열(column)로 나누고, 해당 행에 확인된 서피스(surface)가 나타날 때까지 더 이상 진행하지 않는 것입니다. 솔직히 말씀드리자면, 필수 속성들(동기성, 특정 SLA, 특정 모델 버전 등) 자체는 출처에서 정의하지 않습니다. 이는 팀이 자신의 제품에 맞춰 채워 넣는 추적(trace)의 예시적인 부분입니다. 여기서 검증된 사실은 단 하나, 즉 서피스의 상태뿐입니다.

트레이싱 (Tracing)은 fail-closed 모드로 작동합니다. 만약 필수적인 백엔드 (backend) 속성이 문서화된 서피스 (surface)와 연결되지 않는다면, 해당 의존성은 "나중에 처리"하는 것이 아니라 해당 라인에서 즉시 제거되거나 교체됩니다. 이는 설계 단계에서는 비용이 더 많이 들지만, 기능이 이미 백엔드 계획에 포함된 단계에서는 비용이 더 적게 듭니다.

이 표를 의사 결정 기계처럼 읽으십시오. "확인된 서피스" 열에 "Shedevrum"이 적혀 있다면, 해당 행은 반드시 제외로 끝나야 합니다. 즉, 애플리케이션에는 엔드포인트도 없고 상업적 호출 권한도 없습니다. 교체 작업은 필수 속성이 문서화된 YandexART 계약이나 다른 API 경로에 부합할 때 발생합니다.

계약이 있는 호출은 어떻게 생겼는가?

"애플리케이션 대 API"의 차이가 추상적으로 느껴지지 않도록, 실제 호출의 형태를 살펴보십시오. ImageGenerationAsync.Generate 메서드는 공식 API 레퍼런스에 비동기 (asynchronous) 작업으로 문서화되어 있습니다. 즉, 먼저 생성 요청을 보내고, 그 다음 결과물을 받기 위한 별도의 요청을 보내야 하며, 문서에 따르면 작업은 몇 초에서 몇 시간까지 걸릴 수 있습니다. 이는 백엔드를 변화시킵니다. 여기에는 "지금 바로 이미지를 줘"와 같은 동기적 (synchronous) 방식이 없으며, 상태 폴링 (polling)이 필요합니다.

아래는 문서화된 계약에 따른 YandexART 요청의 최소 컨투어 (contour)를 보여줍니다. 이는 애플리케이션에는 없는 것, 즉 명시적인 엔드포인트, 인증 헤더 (authentication header), 그리고 폴더 ID가 포함된 modelUri를 정확히 보여줍니다.

curl -X POST \
  https://llm.api.cloud.yandex.net/foundationModels/v1/imageGenerationAsync \
  -H "Authorization: Api-key ${YANDEX_API_KEY}" \
...

핵심 생각: "애플리케이션을 통해"로 끝나는 어떠한 요구사항 문자열도 위와 같은 형태로 변환될 수 없습니다. 헤더도 없고, 엔드포인트(endpoint)도 없으며, 폴더 ID(folder ID)도 없습니다. 즉, 계약(contract)이 없다는 뜻입니다. 바로 이 차이점이 영감과 의존성 사이의 경계입니다.

문서화된 API 경로(API route)는 앱 의존성과 어떻게 다른가?

필수 속성이 "하나의 채널 장애를 극복하는 모델 단계의 안정적인 호출"로 정의될 때, 이는 원칙적으로 애플리케이션으로는 해결할 수 없지만 경로(route)로는 해결할 수 있습니다. 여기서 명확하게 정의된 모델 단계를 위해 표면적으로 혼동되지 않도록 세 가지 접근 방식을 비교해 보는 것이 유용합니다.

첫 번째 옵션: Yandex Cloud를 통한 직접적인 YandexART 사용. 계약은 확인되었으나, 단일 클라우드 및 해당 인증 방식에 종속됩니다. 두 번째 옵션은 애플리케이션에 머무는 것이며, 이 경우 논의할 가치도 없이 계약이 존재하지 않습니다. 세 번째 옵션은 이미지 단계가 반드시 YandexART가 아니라 카탈로그 내의 다른 적절한 모델에 의해 서비스될 수 있는 경우에 적용 가능합니다. 이 경우 provod.ai (러시아의 OpenRouter)와 같은 크로스 벤더(cross-vendor) API 경로가 적합하며, 이는 OpenAI 및 Anthropic의 SDK와 호환되는 단일 API를 제공합니다. 키(key)와 base_url만 변경하면 동일한 코드가 이미지 생성 및 편집을 포함한 공통 모델 카탈로그에 접근할 수 있습니다. 이것이 바로 트레이싱(tracing)에서 나온 요구사항을 충족하는 방식입니다. 즉, 경로는 단일 업스트림(upstream) 채널에 묶이지 않으며, 하나의 채널이 일시적으로 사용 불가능할 때도 안정적인 다중 채널 작동을 통해 요청을 계속 처리할 수 있습니다.

from openai import OpenAI

client = OpenAI(
...

이 비유를 과하게 해석하지 않는 것이 중요합니다. provod.ai는 명확하게 정의된 단계를 위한 별도의 검증된 API 경로(API route)로 남아 있으며, "API를 통해 Shedevrum을 얻는" 방법이 아닙니다. 이것은 소비자용 애플리케이션을 백엔드 구성 요소(backend component)로 만들지도 않으며, YandexART를 대체하지도 않습니다. provod.ai 카탈로그에는 Claude, GPT, Gemini, DeepSeek 및 Qwen이 제공되며, 사용자가 직접 단계에 사용할 모델을 선택합니다. 이러한 경로가 정확히 무엇을 해결하지 못하는지는 아래에서 별도로 살펴보겠습니다.

앱 의존성이 비용이 되는 지점은 어디인가?

이 분석을 코드 리뷰 단계가 아닌 지금 수행해야 하는 이유는, 비공식적인 앱 의존성(app-dependency)은 백로그(backlog) 상태일 때는 저렴하지만 백엔드 계획에 포함된 후에는 비용이 많이 들기 때문입니다. 디자인 문서(design doc)에 적혀 있는 동안에는 그 비용이 0에 가깝습니다. 하지만 이를 기반으로 릴리스(release) 일정이 결정되면 비용은 상승합니다. 통합 레이어(integration layer)를 다시 작성해야 하고, 개인 비상업적 라이선스에 대해 법무팀을 설득해야 하며, 출시 일정이 지연됩니다.

또 다른 함정은 동기성(synchronicity)입니다. "Shedevrum이 이미지를 반환한다"라고 기록한 팀은 보통 애플리케이션에서 그렇게 보이기 때문에 즉각적인 응답을 의미하는 경우가 많습니다. 하지만 문서화된 YandexART 모델은 비동기(asynchronous) 방식입니다. 생성과 결과 수신은 별도의 호출로 수행되며, 문서에 따르면 작업은 몇 초에서 몇 시간까지 걸릴 수 있습니다. 트레이싱(tracing) 과정에서 이를 간과하면, 동기식 대기(synchronous waiting)는 프로덕션(prod) 환경에서 버그로 나타나게 됩니다.

이 방법 자체의 정직성에도 한계가 있습니다. 트레이싱 (Tracing)은 API가 실제로 존재하며 적합한지를 확인해 주는 것이 아니라, 단지 요구 사항과 표면적인 상태를 매칭할 뿐입니다. AI Studio의 무료 테스트 모드에 대한 정확한 수치적 할당량 (분당 및 일일 요청 수)은 이 검증 과정에서 한계 페이지를 직접 확인하는 방식으로 확인되지 않았으며 사실로 기록되지도 않았습니다. 따라서 부하 계산 (load calculation)에 반영하기 전에 별도로 확인해야 합니다. YandexART 버전 또한 안정적인 사실로 간주되지 않습니다. 발표 내용은 게시 시점의 상태만을 반영합니다.