VERTEX COMPATIBLE GENERATECONTENT GOOGLE ACCOUNT POOL

Vertex AI image route
tách riêng khỏi GPT.

Client có thể gọi request/response gần với Google Vertex/Gemini REST shape, còn hệ thống vẫn dùng orchestrator, worker Rust nội bộ, account pool đã mã hoá và output publisher hiện có.

01 /v1 02 /v1beta1 03 :generateContent

Vertex-compatible route

POST /v1/projects/{project}/locations/{location}/publishers/google/models/{model}:generateContent

Route này trả Vertex-style GenerateContentResponse với candidates[].content.parts[].inlineData. Header x-gpt-image-job-id giữ internal job id để debug trong console.

Versions v1 / v1beta1

Cùng handler, cùng validation.

Execution Async inside

Orchestrator vẫn tạo job và lưu artifact.

Cache no-store

Response có thể chứa base64 ảnh.

Security

Xác thực bằng key của orchestrator

Client bên ngoài không gửi Google OAuth token trực tiếp. Dùng Bearer credential của hệ thống với scope images:write; output URL cần thêm same-client outputs:read, admin scope hoặc signed URL.

Authorization Bearer gpi_live_... required

Scope	Dùng cho
`images:write`	`:generateContent` và native image generation
`outputs:read`	Tải output URL của cùng API client khi output auth đang bật
`admin:read`	List/read Google accounts
`admin:write`	Import/update/delete/test/reload Google accounts

Google account registry

Credential Google nằm sau orchestrator

Admin import ADC authorized_user hoặc service account JSON qua /v1/google-accounts. Database chỉ lưu ciphertext được mã hoá bằng CREDENTIAL_ENCRYPTION_KEY; worker nhận snapshot redacted qua Docker internal API.

Method	Path	Mục đích
`GET`	`/v1/google-accounts`	List account đã redacted
`POST`	`/v1/google-accounts`	Import credential một lần
`PATCH`	`/v1/google-accounts/{id}`	Đổi model, location, enabled, concurrency hoặc credential
`POST`	`/v1/google-accounts/{id}/test`	Worker mint access token thật để test credential
`POST`	`/v1/google-accounts/reload`	Push snapshot account pool vào workers

Request mapping

Field Vertex được map vào job nội bộ

contents[].parts[].textVertexrequired

Được nối thành prompt nội bộ. Ít nhất một text part hoặc system text phải có nội dung sau khi trim.

contents[].parts[].inlineDataVertex

Chuyển thành reference image dạng data:image/*;base64,... để chạy edit/reference flow.

systemInstruction.parts[].textVertex

Text-only theo docs Google. Inline/file data trong system instruction bị reject.

generationConfig.responseModalitiesVertexrequired

Phải chứa IMAGE. Có thể gửi kèm TEXT.

candidateCount1..4

Map thành n. Orchestrator fan-out nhiều worker calls rồi gom ảnh vào response.

imageConfig.aspectRatioratio

Map sang size/ratio và validate theo model khi model đã biết.

imageConfig.imageSize512/1K/2K/4K

Map sang resolution. 512 hiện chỉ hợp lệ cho gemini-3.1-flash-image.

imageOutputOptions.mimeTypepng/jpeg/webp

Map sang output_format. HEIC/HEIF chưa được publish bởi output store của repo.

Model matrix

Validation theo model Vertex/Gemini

Matrix này mirror audit docs Google ngày 2026-07-05 và implementation Rust hiện tại.

Model	Max input images	Aspect ratios	Image sizes
`gemini-2.5-flash-image`	3	`1:1`, `3:2`, `2:3`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`	`1k`, `2k`, `4k`
`gemini-3-pro-image`	14	`1:1`, `3:2`, `2:3`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`	`1k`, `2k`, `4k`
`gemini-3.1-flash-image`	14	`1:1`, `3:2`, `2:3`, `3:4`, `1:4`, `4:1`, `4:3`, `4:5`, `5:4`, `1:8`, `8:1`, `9:16`, `16:9`, `21:9`, `9:21`	`512`, `1k`, `2k`, `4k`
`gemini-3.1-flash-lite-image`	14	`1:1`, `1:4`, `4:1`, `1:8`, `8:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`	`1k`

Output storage

Ảnh vẫn được lưu qua output publisher

Worker trả inlineData.data, orchestrator decode bytes, ghi RustFS/S3 hoặc filesystem fallback, xoá data_base64 khỏi metadata job, rồi Vertex route đọc lại object bytes để trả base64 cho client.

Header debug x-gpt-image-job-id: <internal-job-uuid>

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "..."
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {},
  "modelVersion": "gemini-3.1-flash-image"
}

Error contract

Google status kèm public taxonomy

Error body vẫn giữ error.status kiểu Google và thêm error.type, error.request_id giống các public route khác. Gửi X-Request-Id printable ASCII tối đa 128 bytes để correlate với log client.

{
  "error": {
    "code": 400,
    "message": "generationConfig.responseModalities must include IMAGE",
    "status": "INVALID_ARGUMENT",
    "type": "invalid_request",
    "request_id": "client-request-123"
  }
}

HTTP	Google status	Public type
`400`	`INVALID_ARGUMENT`	`invalid_request`
`401`	`UNAUTHENTICATED`	`unauthorized` hoặc `provider_auth_failed`
`403`	`PERMISSION_DENIED`	`forbidden`
`429`	`RESOURCE_EXHAUSTED`	`rate_limited` hoặc `provider_quota_limited`
`502/503`	`UNAVAILABLE`	`worker_unavailable`, `provider_rejected` hoặc `internal_error`
`504`	`DEADLINE_EXCEEDED`	`timeout`

Known gaps

Phạm vi hiện tại

fileData với gs:// image object đã được forward; tools, toolConfig, safetySettings, modelArmorConfig, cachedContent và labels chưa được forward.
Streaming streamGenerateContent chưa có route riêng.
Multi-turn conversation semantics đang được flatten thành một prompt nội bộ.
HEIC/HEIF chưa được publish vì output store, thumbnailing và browser behavior chưa được chuẩn hoá.

Real gate: just vertex-real-e2e với VERTEX_CREDENTIAL_JSON_PATH, VERTEX_PROJECT_ID, VERTEX_LOCATION, VERTEX_MODEL và CREDENTIAL_ENCRYPTION_KEY. Static doc URL: /docs/vertex-ai/ · markdown source: docs/vertex-ai-api.md