canonical_url: https://yycode.net/docs/vi/gpt-image-quickstart lang: vi updated_at: 2026-07-04T13:33:48.616Z source_html: https://yycode.net/docs/vi/gpt-image-quickstart # Hướng dẫn sử dụng GPT-Image-2 GPT-Image-2 là dịch vụ tạo ảnh AI do YYCode cung cấp, sử dụng giao diện ảnh độc lập `gpt.yycode.net` để hoàn thành text-to-image, image-to-image và truy vấn tác vụ bất đồng bộ. --- ## Chuẩn bị ### 1. Tạo API Key Vào [trang quản lý token YYCode](https://yycode.net/console/token), tạo hoặc sao chép API Key. Sau khi tạo xong, vui lòng lưu giữ cẩn thận; tất cả request tiếp theo đều cần mang Key này trong Header. ### 2. Địa chỉ giao diện GPT-Image-2 sử dụng Base URL độc lập: ``` https://gpt.yycode.net ``` Tất cả request ảnh đồng thời mang địa chỉ trạm trung chuyển YYCode: ``` x-demo-base-url: https://yycode.net ``` --- ## AI Agent kết nối một bước Khi dùng các công cụ AI coding hỗ trợ Skills như Claude Code, Codex, hãy gửi trực tiếp nội dung sau cho AI: ```text Vui lòng tích hợp dịch vụ tạo ảnh YYCode GPT-Image-2 cho dự án này. Base URL: https://gpt.yycode.net Text to Image: POST /api/images/generate Image to Image: POST /api/images/edit Truy vấn tác vụ: GET /api/jobs/{jobId} Request Header: x-demo-base-url: https://yycode.net x-demo-api-key: YOUR_API_KEY x-demo-async: 1 Text to Image dùng JSON request body; Image to Image dùng multipart/form-data và upload ảnh gốc bằng field image. Sau khi submit tác vụ trả về jobId, truy vấn /api/jobs/{jobId} mỗi 6 giây. Khi trả về status=succeeded, đọc images[].b64 và images[].mimeType, lưu base64 thành file ảnh. ``` AI Agent sẽ theo giao diện, Header, cách polling và cách lưu ảnh ở trên để hoàn tất tích hợp mã client. --- ## Chi tiết API ### Text to Image Submit tác vụ tạo ảnh: ```bash curl 'https://gpt.yycode.net/api/images/generate' \ -H 'Content-Type: application/json' \ -H 'x-demo-base-url: https://yycode.net' \ -H 'x-demo-api-key: YOUR_API_KEY' \ -H 'x-demo-async: 1' \ -d '{ "model": "gpt-image-2", "prompt": "Một chú mèo dễ thương đang ngủ gật dưới ánh nắng", "n": 1, "size": "1024x1024" }' ``` Phản hồi thành công: ```json { "ok": true, "pending": true, "jobId": "job_1782732290788_3", "meta": { "requestId": "req_1782732290788_1" } } ``` ### Truy vấn kết quả tác vụ Thay `job_1782732290788_3` bằng `jobId` trả về khi submit tác vụ: ```bash curl 'https://gpt.yycode.net/api/jobs/job_1782732290788_3' ``` **Đang xử lý tác vụ:** ```json { "ok": true, "pending": true, "jobId": "job_1782732290788_3", "status": "running", "meta": { "requestId": "req_1782732290788_1" } } ``` **Tác vụ hoàn tất:** ```json { "ok": true, "images": [ { "b64": "iVBORw0KGgo...", "filename": null, "mimeType": "image/png" } ], "usage": null, "raw": {}, "meta": { "requestId": "req_1782732290788_1" }, "jobId": "job_1782732290788_3", "status": "succeeded" } ``` Dữ liệu ảnh cuối cùng là `images[0].b64`, định dạng ảnh là `images[0].mimeType`. Khi hiển thị ở frontend, dùng `data:${mimeType};base64,${b64}`; khi tải xuống, giải mã base64 thành file ảnh. --- ### Image to Image Image to Image dùng `multipart/form-data` upload ảnh gốc và submit file ảnh qua field `image`. **Upload một ảnh gốc:** ```bash curl 'https://gpt.yycode.net/api/images/edit' \ -H 'x-demo-base-url: https://yycode.net' \ -H 'x-demo-api-key: YOUR_API_KEY' \ -H 'x-demo-async: 1' \ -F 'model=gpt-image-2' \ -F 'prompt=Chuyển bức ảnh này sang phong cách màu nước' \ -F 'n=1' \ -F 'size=1024x1024' \ -F 'image=@input.png' ``` **Upload nhiều ảnh gốc:** ```bash curl 'https://gpt.yycode.net/api/images/edit' \ -H 'x-demo-base-url: https://yycode.net' \ -H 'x-demo-api-key: YOUR_API_KEY' \ -H 'x-demo-async: 1' \ -F 'model=gpt-image-2' \ -F 'prompt=Tham khảo những ảnh này để tạo poster phong cách cyberpunk thống nhất' \ -F 'n=1' \ -F 'size=1536x1024' \ -F 'image=@subject.png' \ -F 'image=@style.png' ``` **Lưu ý về Image to Image:** - `image` là field file ảnh; khi upload nhiều ảnh, truyền lặp lại `image` - `mask` là field file mask ảnh, dùng cho chỉnh sửa cục bộ - Không tự đặt request header `Content-Type`; để `curl` hoặc SDK tự sinh multipart boundary - Tác vụ Image to Image cũng trả về `jobId` và truy vấn kết quả qua `GET /api/jobs/{jobId}` --- ## Tham số | Tham số | Mô tả | |---|---| | `model` | cố định điền `gpt-image-2` | | `prompt` | prompt tạo ảnh hoặc chỉnh sửa ảnh | | `n` | số lượng ảnh tạo, phạm vi `1` đến `10` | | `size` | kích thước ảnh đầu ra, định dạng `x` | | `output_format` | định dạng đầu ra, hỗ trợ `png`, `jpeg`, `webp` | | `quality` | chất lượng ảnh, hỗ trợ `auto`, `low`, `medium`, `high`, `standard`, `hd` | | `background` | chế độ nền, hỗ trợ `auto`, `opaque` | | `image` | field file ảnh gốc cho Image to Image, hỗ trợ truyền lặp | | `mask` | field file mask cho Image to Image, dùng cho chỉnh sửa cục bộ | ### Hỗ trợ size `size` dùng kích thước pixel thật; chiều rộng và chiều cao đều là bội số của `16`, cạnh dài nhất không vượt quá `3840`, tổng pixel không vượt quá `3840x2160`. | Kích thước | Mô tả | |---|---| | `1024x1024` | ảnh vuông | | `1536x1024` | ảnh ngang | | `1024x1536` | ảnh dọc | | `1920x1080` | ảnh ngang HD | | `1080x1920` | ảnh dọc HD | | `3840x2160` | ảnh ngang 4K | | `2160x3840` | ảnh dọc 4K | --- ## Ví dụ Python ```python import base64 import time import requests # Thay bằng YYCode API Key của bạn base_url = "https://gpt.yycode.net" api_key = "YOUR_API_KEY" headers = { "Content-Type": "application/json", "x-demo-base-url": "https://yycode.net", "x-demo-api-key": api_key, "x-demo-async": "1", } # Bước 1: submit tác vụ Text to Image submit = requests.post( f"{base_url}/api/images/generate", headers=headers, json={ "model": "gpt-image-2", "prompt": "Một chú mèo dễ thương đang ngủ gật dưới ánh nắng", "n": 1, "size": "1024x1024", }, timeout=30, ) submit.raise_for_status() job_id = submit.json()["jobId"] print(f"Tác vụ đã submit: {job_id}") # Bước 2: polling trạng thái tác vụ mỗi 6 giây while True: result = requests.get( f"{base_url}/api/jobs/{job_id}", timeout=30, ) result.raise_for_status() data = result.json() if data.get("pending"): print("Tác vụ đang xử lý...") time.sleep(6) continue if data.get("status") == "succeeded": # Bước 3: lưu ảnh base64 thành file local image = data["images"][0] mime_type = image.get("mimeType") or "image/png" suffix = mime_type.split("/")[-1].replace("jpeg", "jpg") filename = f"{job_id}.{suffix}" with open(filename, "wb") as file: file.write(base64.b64decode(image["b64"])) print(f"Tạo ảnh hoàn tất: {filename}") break raise RuntimeError(data.get("error", {}).get("message", "Tác vụ thất bại")) ``` --- ## Giải thích tính phí - Tạo ảnh tiêu tốn hạn mức tài khoản YYCode thuộc `x-demo-api-key` - Submit tác vụ trả về `jobId` nghĩa là tác vụ backend đã được tạo - Khi trạng thái tác vụ là `succeeded` và trả về `images`, lần tạo ảnh này hoàn tất - Khi trạng thái tác vụ là `failed`, phản hồi sẽ trả về thông tin lỗi - Bản ghi sử dụng tài khoản được hiển thị trong backend YYCode --- ## Giải thích dữ liệu ảnh trả về Giao diện ảnh YYCode trả về mảng `images` đã chuẩn hóa. Mỗi ảnh chứa trường `b64` và `mimeType`; bên tích hợp dùng `b64` để giải mã lưu file, hoặc ghép `data:${mimeType};base64,${b64}` để hiển thị ở frontend.