Google Flow API를 통해 Google Flow Agent와 채팅하는 방법

서론

useapi.net의 Google Flow API를 사용하면 코드를 이용해 Google Flow에 내장된 크리에이티브 어시스턴트인 Google Flow Agent와 채팅할 수 있습니다. 단 한 번의 curl로 채팅을 시작하고, 그 답변을 스트리밍하며, 지출 승인을 하고, 생성된 이미지와 비디오를 다운로드할 수 있습니다.
Google은 Flow Agent를 Flow 웹 앱 내부에서만 제공하며, 공개 API는 없습니다 (2026년 10월 기준). useapi.net은 Google과 제휴하지 않은 제3자(third-party) API이며, 채팅은 사용자의 자체 Google 계정에서 실행됩니다. 에이전트와의 채팅에는 크레딧 비용이 들지 않으며, 생성된 이미지와 비디오는 일반적인 Flow 가격을 따릅니다.

본 가이드는 시작부터 끝까지의 실제 실행 과정을 다룹니다. 우리는 에이전트에게 세라믹 커피 머그 제품 컷 두 장과 해당 제품의 6초짜리 비디오를 요청하고, 지출을 승인했으며, 미디어를 수집한 후, 수정본을 요청했다가 그 결과는 거부했습니다. 아래의 모든 응답은 해당 실행 과정에서 나온 것이며, 내용은 간추리고 계정 이메일 주소만 대체되었습니다.

에이전트가 작업을 자체적으로 계획합니다. 프로젝트 설정에 따라 도구와 모델을 선택하며, 전체 대화 내용을 Google 측에 유지하므로, 완전한 컨텍스트를 가지고 몇 시간 또는 며칠 후에 채팅을 계속할 수 있습니다. Agent Overview에서 모든 규칙과 제한 사항을 확인할 수 있습니다.

시작하기 전에

useapi.net의 API 토큰과 Google Flow 설정(Setup Google Flow)을 통해 연결된 Google 계정이 필요합니다. 이 에이전트는 무료 계정을 포함하여 모든 Google AI 플랜에서 작동하며, 생성할 수 있는 내용은 POST /images 및 POST /videos와 동일하게 계정의 플랜을 따릅니다.

각 턴(turn)은 하나의 캡차(captcha)를 사용하며, 이 캡차는 captcha providers를 통해 API로 해결하거나 첫 번째 계정의 무료 캡차 크레딧을 사용합니다. 사용자 측에서는 아무것도 전송할 필요가 없습니다.

단계는 curl, jq 및 세 개의 셸 변수를 사용합니다:

export USEAPI_TOKEN="user:12345-..."   # useapi.net API 토큰
export EMAIL="[email protected]"           # 연결된 Google Flow 계정
API="https://api.useapi.net/v1/google-flow/agent"

아래의 모든 호출은 Postman 컬렉션에도 포함되어 있습니다.

채팅 작동 방식

턴(turn)이란 사용자로부터 온 하나의 메시지와 에이전트가 응답으로 수행하는 모든 것을 의미합니다. 채팅은 한 턴씩 진행됩니다:

1. POST /agent/chats를 사용하여 채팅을 시작하고, chatId와 함께 202 응답을 반환합니다.
2. GET /agent/chats/chatId/stream를 사용하여 서버 전송 이벤트(Server-Sent Events)를 통해 에이전트의 실시간 진행 상황을 추적합니다.
3. 에이전트가 크레딧을 사용해야 할 경우, 멈추고 요청하며 POST /agent/chats/chatId/approval를 통해 승인합니다.
4. POST /agent/chats/chatId/messages로 다음 메시지를 전송합니다.
5. GET /agent/chats/chatId를 사용하여 최신 미디어 링크와 함께 전체 채팅 내용을 읽습니다.

1단계: 채팅 시작

간략한 내용(brief)을 message로 전송합니다. 호출은 Google이 해당 턴을 수락하는 즉시 반환되는데, 이는 보통 몇 초가 걸리며 최대 약 100초까지 소요될 수 있으므로, curl에 150초의 타임아웃을 설정해야 합니다:

curl -s --max-time 150 -X POST "$API/chats" \
  -H "Authorization: Bearer $USEAPI_TOKEN" \
  -H "Content-Type: application/json" \
...

저희는 약 10초 만에 202 응답을 받았습니다:

chatId는 계정과 프로젝트를 명시하며, 따라서 이후 호출에서는 필요하지 않습니다. :와 @ 기호가 포함되어 있으므로 경로에서 URL 인코딩해야 합니다. 두 가지 형태 모두 유지하세요:

CHATID="c-u12345-email:[email protected]:74262ac8-...-bot:google-flow"
CHAT=$(jq -rn --arg v "$CHATID" '$v|@uri')

projectId가 없으면, 채팅은 계정 자체 에이전트 프로젝트에 존재하며, 첫 채팅 시 생성되고 My Agents Work Fri, Oct 16과 같이 이름 지어지므로 에이전트 작업이 다른 Flow 미디어와 분리됩니다. 또한 POST /videos에서와 동일한 @-멘션 구문을 사용하여 최대 7개의 이미지, 비디오 1개, 음성(voice) 5개, 캐릭터 7개를 모든 메시지에 첨부할 수 있습니다. POST /agent/chats를 참조하세요.

2단계: 답변 스트리밍하기

이벤트가 도착하는 대로 출력되도록 -N 옵션을 사용하여 스트림을 엽니다. 브라우저의 EventSource는 Authorization 헤더를 보낼 수 없으므로, 앱에서 fetch() 또는 모든 HTTP 클라이언트를 사용하세요:

curl -s -N "$API/chats/$CHAT/stream" \
  -H "Authorization: Bearer $USEAPI_TOKEN"

새 스트림은 먼저 chat 이벤트를 보내고, 채팅 기록을 재생(replays)한 다음, replayed를 보냅니다. replayed 이후의 모든 내용은 실시간입니다. 여기서는 연결했을 때 첫 번째 턴이 이미 끝났기 때문에 재연(replay)으로 들어왔습니다. 에이전트는 계획을 진술한 후, 이미지 2개와 비디오 1개에 대해 10 크레딧을 사용할 권한을 요청했습니다 (ui 및 기타 긴 필드는 생략):

event: chat
data: {"chatId":"c-u12345-email:[email protected]:74262ac8-...-bot:google-flow","status":"waiting_approval","turns":1}

...

사용자가 처리해야 하는 이벤트는 다음과 같습니다:

단계 3: 비용 승인(Approve spending)

ask 승인 모드에서는 에이전트가 어떤 것도 사용하기 전에 멈춥니다. 채팅의 status는 waiting_approval이며, approval 이벤트에서 비용을 보여줍니다. approve, always 또는 reject로 답변하세요:

curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \
  -H "Authorization: Bearer $USEAPI_TOKEN" \
  -H "Content-Type: application/json" \
...

답변은 새로운 턴을 시작하며, 이는 사용자의 메시지와 동일합니다:

{
  "chatId": "c-u12345-email:[email protected]:74262ac8-...-bot:google-flow",
  "email": "[email protected]",
...

열린 스트림에서 턴 2는 비디오를 대기열에 넣고, 두 개의 이미지를 만들었으며 약 30초 만에 종료되었습니다. 에이전트의 choices (Option 1, Option 2)는 Flow 웹 앱에서 각 결과에 대해 표시되는 타일입니다:

id: 2:5feb253e-0848-422a-bcb8-936995b3c0df
events: message
data: {"id":"2:5feb253e-...","turn":2,"items":[{"kind":"tool_result","tool":"generate_video_from_text","result":{"status":"queued","media_id":"5732c66d-a971-4cd0-92d2-508ef0aecc07","display_name":"커피 머그에서 피어오르는 증기","model_key":"abra_t2v_6s","aspect_ratio":"VIDEO_ASPECT_RATIO_LANDSCAPE"}}]}
...

always는 승인하고 프로젝트를 auto 모드로 전환하며, 따라서 에이전트는 프로젝트의 모든 채팅에서 묻는 것을 중단합니다. reject는 거부하며, 이는 단계 5에 표시됩니다. 답변하는 대신 새 메시지를 보내는 것도 생성 없이 진행하게 합니다.

단계 4: 미디어 가져오기

이미지는 턴(turn)이 끝날 때 준비됩니다. 비디오는 보통 1~2분 후에 완료되며, 스트림은 완료될 때 두 번째 media 이벤트를 전송합니다. 저희의 경우 턴이 끝난 지 1분도 채 되지 않아 다음과 같이 도착했습니다:

id: 2:m:5732c66d-a971-4cd0-92d2-508ef0aecc07
event: media
data: {"turn":2,"referenceId":"user:12345-email:6a6f...-video:5732c66d-a971-4cd0-92d2-508ef0aecc07","mediaId":"5732c66d-a971-4cd0-92d2-508ef0aecc07","type":"video","status":"completed","tool":"generate_video_from_text","model":"abra_t2v_6s","displayName":"커피 머그에서 피어오르는 증기","url":"https://flow-content.google/video/5732c66d-...?Expires=...&Signature=...","durationSec":6}

url을 받은 즉시 다운로드하세요:

curl -s -L -o mug-steam.mp4 "https://flow-content.google/video/5732c66d-...?Expires=...&Signature=..."

이 링크들은 Google에서 제공되며 발급된 후 약 6시간 후에 만료됩니다. 최신 링크를 받으려면 GET /agent/chats/chatId``로 채팅 기록을 다시 읽거나, 해당 referenceId를 사용하여 GET /assets/mediaGenerationId에서 항목의 링크를 얻을 수 있습니다. 이 referenceId는 또한 POST /images, POST /videos 및 다음 에이전트 메시지에서 referenceImage_N 또는 referenceVideo_1로 사용될 수 있습니다. 예시의 두 이미지와 1280×720 비디오가 그렇습니다.

이번 실행에는 크레딧 10개가 소모되었습니다. Nano Banana 2.1 이미지 두 개는 이 계정 플랜에서 비용이 0이었고, 6초짜리 Omni 1.1 Flash 비디오는 10을 소비했습니다.

단계 5: 계속하거나 수정하기

같은 채팅에 다음 메시지를 보내세요. Google은 대화 내용을 유지하므로 에이전트는 어떤 비디오가

이전 청크와 일관된 용어 및 톤을 유지하며 번역합니다.

id: 3:approval
event: approval
data: {"turn":3,"cost":12,"images":0,"videos":1,"total":1}
...

비디오가 있었기 때문에 거절했습니다:

curl -s --max-time 150 -X POST "$API/chats/$CHAT/approval" \
  -H "Authorization: Bearer $USEAPI_TOKEN" \
  -H "Content-Type: application/json" \
...

턴 4는 응답으로 끝나고 생성은 없었으며, 크레딧도 소모되지 않았습니다:

id: 4:91e06fb7-ba5b-4e32-b2a6-ce210be491ba
event: message
data: {"id":"4:91e06fb7-...","turn":4,"items":[{"kind":"text","text":"I've cancelled that generation. Are there any changes you'd like to make to the prompt or concept before we try again?"}]}
...

턴이 진행되는 동안 메시지를 보내면 409 오류가 발생하므로, 먼저 turn 이벤트를 기다려야 합니다. 에이전트의 선택지 중 하나를 선택하려면, Flow 웹 앱에서 하는 것처럼 해당 선택지의 텍스트를 다음 메시지로 전송합니다.

6단계: 채팅 읽기, 목록 보기, 이름 변경 및 삭제

Google에서 언제든지 전체 채팅 내용을 읽을 수 있습니다. 각 턴에는 사용자의 메시지, 에이전트가 수행한 모든 작업, 그리고 새로운 링크와 함께 미디어 자료가 포함됩니다:

curl -s "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN"

네 번의 턴을 거친 우리의 채팅 내용(에이전트 항목과 미디어를 간소화하고, UI는 제외):

{
  "chatId": "c-u12345-email:[email protected]:74262ac8-...-bot:google-flow",
  "email": "[email protected]",
...
}

Google이 자체적으로 채팅 제목을 지정했습니다. status가 아무것도 실행되지 않으면 idle이며, 에이전트가 기다리는 동안 비용은 pendingApproval 상태를 유지합니다. 링크 새로고침 없이 더 빠르게 읽으려면 ?media=false를 전달하세요.

계정의 채팅 목록을 최신 활동 순으로 가져옵니다. 이 목록은 Google에서 제공되므로, 동일한 프로젝트 내 Flow 웹 앱에서 시작된 채팅도 포함하며, 잃어버린 chatId를 찾는 방법이기도 합니다:

curl -s "$API/chats?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN"

채팅 이름 변경. 새 제목은 Flow 웹 앱에서도 표시됩니다:

curl -s -X PATCH "$API/chats/$CHAT" \
  -H "Authorization: Bearer $USEAPI_TOKEN" \
  -H "Content-Type: application/json" \
...

목록은 다음과 같이 표시됩니다:

{
  "chats": [
    {
...

채팅의 대화를 삭제합니다. 이 경우 204 응답과 본문 없이 처리되며, 해당 채팅은 목록과 Flow 웹 앱에서 사라지지만, 생성된 이미지와 비디오는 프로젝트에 그대로 유지됩니다:

curl -s -X DELETE "$API/chats/$CHAT" -H "Authorization: Bearer $USEAPI_TOKEN"

턴(turn)이 진행되는 동안 답변을 이름 변경하고 삭제합니다.

7단계: 승인, 지침 및 기본 모델 설정

각 Flow 프로젝트는 Flow 웹 앱의 에이전트 패널과 동일한 에이전트 설정을 가지고 있습니다. GET /agent/settings가 이를 읽어오며, 계정의 Google 플랜에 포함된 이미지 및 비디오 모델 목록과 해당 플랜에서 하나를 생성하는 데 드는 비용을 나열합니다:

curl -s "$API/settings?email=$EMAIL" -H "Authorization: Bearer $USEAPI_TOKEN"