문서 / AI 연결과 게이트웨이

AI 연결과 게이트웨이

OpenRouter API 키를 연결하고 채팅, 임베딩, 이미지 생성 기능을 사용하는 방법을 알아봅니다.

프로젝트에 OpenRouter 키 연결하기

  1. OpenRouter 키 준비

    OpenRouter 공식 홈페이지에서 사용할 API 키를 발급받으세요. 모델 찾아보기에서 채팅, 임베딩, 이미지 생성 중 원하는 작업을 지원하는 모델을 고르고 모델 ID를 확인하세요.

  2. 프로젝트의 AI 연결 탭 열기

    프로젝트를 선택한 뒤 AI 연결 탭에 API 키를 입력하고 저장하세요. 프로젝트 소유자와 편집자는 키를 등록하거나 교체하고, 연결을 해제할 수 있습니다.

  3. 서버 코드에서 호출

    키를 저장하면 서버 코드에서 env.OPENROUTER_API_KEY와 env.AI_GATEWAY를 사용할 수 있습니다. 게이트웨이 주소를 따로 입력하지 않아도 됩니다.

AI 요청에는 직접 등록한 OpenRouter 키를 사용합니다. 키는 프로젝트 Worker의 Secret에 저장되며, 저장한 값은 화면에서 다시 확인할 수 없습니다. 키를 바꾸려면 새 키를 저장하고, 삭제하려면 연결을 해제하세요. 키를 브라우저 코드나 Git, 로그에 넣거나 에이전트와의 대화에 붙여 넣지 마세요.

run(model, input, options)

env.AI_GATEWAY.run()은 프로젝트의 서버 코드에서 호출하세요. 아래 예제는 Hono 서버의 요청 핸들러 안에서 사용하는 코드입니다. 앱 이용자의 로그인과 권한을 먼저 확인한 뒤 호출하세요. 예제의 env는 Hono의 c.env를 가리킵니다.

JavaScript
const response = await env.AI_GATEWAY.run(model, input, { apiKey, task });
model · 필수
사용할 OpenRouter 모델의 ID입니다. 예제의 모델 ID를 원하는 작업을 지원하는 실제 모델 ID로 바꾸세요.
input · 필수
모델에 보낼 내용을 담는 객체입니다. 채팅 메시지는 messages, 임베딩할 텍스트는 input, 이미지 설명은 prompt에 넣으세요.
options.apiKey · 필수
프로젝트에 저장한 키를 env.OPENROUTER_API_KEY로 전달하세요.
options.task · 필수
chat, embeddings, image 중 하나를 지정하세요. 생략하거나 다른 값을 넣으면 OpenRouter로 요청을 보내기 전에 400 오류를 반환합니다.
반환값
Response 객체를 반환합니다. 스트리밍 응답은 그대로 반환하세요. JSON 응답을 읽을 때는 response.ok로 성공 여부를 확인한 뒤 response.json()을 호출하세요.

채팅과 스트리밍

채팅을 지원하는 모델을 고르고, messages에 대화 내용을 넣으세요. stream: true로 설정하면 답변을 SSE 스트림으로 받을 수 있습니다. 이때는 response.json()으로 읽지 말고 응답을 그대로 반환하세요.

JavaScript
const env = c.env;
const response = await env.AI_GATEWAY.run(
  "<CHAT_MODEL_ID>",
  {
    messages: [{ role: "user", content: "Hello" }],
    stream: true,
  },
  { apiKey: env.OPENROUTER_API_KEY, task: "chat" },
);
return response;

텍스트 임베딩

임베딩 모델을 고르고, input에 텍스트 한 개 또는 텍스트 배열을 넣으세요. 요청이 성공하면 JSON 응답의 data[].embedding에서 벡터를 확인할 수 있습니다. 벡터와 원문을 저장하거나 검색에 활용하는 부분은 앱에서 구현하세요.

JavaScript
const env = c.env;
const response = await env.AI_GATEWAY.run(
  "<EMBEDDING_MODEL_ID>",
  { input: ["Hello", "World"] },
  { apiKey: env.OPENROUTER_API_KEY, task: "embeddings" },
);
return response;

이미지 생성

OpenRouter Image API를 지원하는 모델을 고르고, prompt에 만들고 싶은 이미지를 설명하세요. 아래 예제는 이미지 한 장을 요청합니다. 생성이 완료되면 JSON 응답의 data[].b64_json에서 Base64로 인코딩된 이미지를 확인할 수 있습니다. 응답에 media_type이 포함되어 있으면 이미지 형식도 확인할 수 있습니다. 모델마다 사용할 수 있는 옵션은 OpenRouter 이미지 생성 문서에서 확인하세요.

JavaScript
const env = c.env;
const response = await env.AI_GATEWAY.run(
  "<IMAGE_MODEL_ID>",
  { prompt: "A cat sitting by a sunny window", n: 1 },
  { apiKey: env.OPENROUTER_API_KEY, task: "image" },
);
return response;

오류 처리와 호출 권한 확인하기

  • task를 생략하거나 지원하지 않는 값을 넣으면 400 오류가 발생합니다. 모델 ID가 비어 있거나 문자열이 아닌 경우, 입력값이 객체가 아닌 경우에도 400 오류가 발생합니다.
  • API 키가 없거나 형식이 올바르지 않으면 401 오류가 발생합니다. OpenRouter가 오류를 반환한 경우에는 해당 HTTP 상태 코드를 유지하며, 응답에 upstream_status와 간단한 오류 메시지가 포함됩니다.
  • OpenRouter에 연결하지 못하면 502 오류가 발생합니다. 바인딩을 호출하는 과정에서 예외가 발생할 수도 있으므로 앱의 오류 처리 코드에서도 이에 대비하세요.
  • API 키는 서버에서만 사용하세요. 앱에서도 AI를 호출하는 이용자의 로그인과 권한을 확인하고, 필요한 호출 제한을 설정하세요. 프로젝트의 AI 연결 관리 기능은 앱 이용자의 호출 권한까지 확인해 주지 않습니다.
  • 키나 프롬프트, AI 응답 원문을 로그에 남기지 마세요. HTTP 요청이 성공했더라도 스트리밍 도중 오류가 발생할 수 있습니다. 앱에서 스트림을 읽을 때 오류 메시지도 확인하세요.

앱 로그인·권한 가이드와 프로젝트 AI 연결 화면을 함께 확인하세요.

문서 전체 보기프로젝트 열기