Tokatlas

外觀

English
圖像生成

圖像生成概覽 ​

從文字生成圖像，並將結果下載到本機。

本頁使用 OpenAI 相容圖像路由：POST /v1/images/generations。非串流請求直接傳回 data[].url 或 data[].b64_json，以下範例會將結果存到本機。Nano Banana 原生路由請見 Nano Banana。

多語言 API 呼叫 ​

執行方式見多語言範例說明。先設定 API_KEY，並替換模型、檔案網址及 ID 占位值；四種方式會顯示相同請求的原始回應。

此處顯示 API 原始回應；圖片的 Base64 解碼、下載與保存請接續本頁或圖像概覽的完整流程。

bash
curl --fail-with-body --silent --show-error --max-time 180 \
  --request POST \
  --url "https://api.tokatlas.ai/v1/images/generations" \
  --header "Authorization: Bearer $API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "YOUR_ENABLED_IMAGE_MODEL_ID",
  "prompt": "A white ceramic cup on a pale gray background, studio lighting",
  "n": 1
}'
python
import os
import requests

headers = {
    'Authorization': 'Bearer ' + os.environ["API_KEY"],
    'Content-Type': 'application/json',
}
payload = {'model': 'YOUR_ENABLED_IMAGE_MODEL_ID',
 'prompt': 'A white ceramic cup on a pale gray background, studio lighting',
 'n': 1}
response = requests.request(
    'POST', 'https://api.tokatlas.ai/v1/images/generations', headers=headers,
    json=payload,
    timeout=180,
)
response.raise_for_status()
print(response.text)
js
if (!process.env.API_KEY) throw new Error("Set API_KEY first.");
const response = await fetch("https://api.tokatlas.ai/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "YOUR_ENABLED_IMAGE_MODEL_ID",
  "prompt": "A white ceramic cup on a pale gray background, studio lighting",
  "n": 1
}),
  signal: AbortSignal.timeout(180_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.text());
java
import java.net.URI;
import java.net.http.*;
import java.time.Duration;

public class Example {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("API_KEY");
        if (apiKey == null || apiKey.isBlank()) {
            throw new IllegalArgumentException("Set API_KEY first.");
        }
        String payload = String.join("\n",
            "{",
            "  \"model\": \"YOUR_ENABLED_IMAGE_MODEL_ID\",",
            "  \"prompt\": \"A white ceramic cup on a pale gray background, studio lighting\",",
            "  \"n\": 1",
            "}"
        );
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(30)).build();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.tokatlas.ai/v1/images/generations"))
            .timeout(Duration.ofSeconds(180))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();
        HttpResponse<String> response = client.send(
            request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": "
                + response.body());
        }
        System.out.println(response.body());
    }
}

1. 準備 ​

先依 API 使用入門取得金鑰與可用模型。IMAGE_MODEL_ID 必須是支援 /v1/images/generations 的圖像模型；文字模型不能用於此端點。安裝 Python 3，並在終端機執行：

bash
python3 -m pip install requests
export API_KEY='YOUR_TOKATLAS_API_KEY'
export IMAGE_MODEL_ID='YOUR_ENABLED_IMAGE_MODEL_ID'

2. 生成並儲存 ​

將下方存為 generate_image.py，執行 python3 generate_image.py。成功後目前目錄會出現 generated-0.image；檔案包含原始圖像資料，可用圖片檢視器開啟，副檔名請依實際格式調整。

python
import base64
import os
from pathlib import Path
import requests

base = os.environ.get("API_BASE_URL", "https://api.tokatlas.ai").rstrip("/")
response = requests.post(
    base + "/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={"model": os.environ["IMAGE_MODEL_ID"],
          "prompt": "A white ceramic cup on a pale gray background, studio lighting",
          "n": 1},
    timeout=180,
)
response.raise_for_status()
body = response.json()
if not isinstance(body.get("data"), list) or not body["data"]:
    raise RuntimeError(f"Missing image data: {body}")
for index, item in enumerate(body["data"]):
    if item.get("b64_json"):
        data = base64.b64decode(item["b64_json"], validate=True)
    elif item.get("url"):
        download = requests.get(item["url"], timeout=120)
        download.raise_for_status()
        data = download.content
    else:
        raise RuntimeError(f"Expected an image, received: {item}")
    path = Path(f"generated-{index}.image")
    path.write_bytes(data)
    print(f"Saved {path}: {len(data)} bytes")

3. 調整與排錯 ​

  • 先只傳 model、prompt、n: 1。成功後再依模型加入 size、quality 等參數，避免混用比例與像素尺寸。
  • 401／403：重新檢查金鑰與模型權限；400：查看錯誤本文，核對模型及參數。
  • 404 或不支援模型：確認所選路由支援圖像生成；原生 Gemini 圖像模型請使用 Nano Banana 頁面的路徑。
  • 只收到 task_id：目前使用的是其他異步路由，與本頁回包不同；不要把 ID 當成圖片 URL，請切換到符合本頁格式的路由。
  • 超時後先查看用量／請求記錄，確認結果再重新提交，避免重複生成。圖像 URL 的效期依路由而定，取得後及時保存。

參考圖編輯請見檔案分析，聊天工具整合請見工具呼叫。