> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Tạo biến thể hình ảnh

> Tạo biến thể của một hình ảnh cho trước

## Tổng quan

Endpoint này được giữ lại cho client tạo biến thể legacy tương thích OpenAI. Đây không phải đường dẫn được khuyến nghị cho workflow image-to-image hiện tại; hãy dùng `/v1/images/edits` với `gpt-image-2` hoặc `/v1/images/generations` với model image-to-image như `nano-banana-pro` khi có thể. Yêu cầu `multipart/form-data`.

## Nội dung yêu cầu

**Timeout cho yêu cầu đồng bộ:** một số nhà cung cấp hình ảnh được định tuyến sẽ trả ảnh cuối cùng inline và chờ quá trình tạo hoàn tất. Yêu cầu độ phân giải cao hoặc chất lượng cao có thể mất gần một phút hoặc lâu hơn, vì vậy hãy đặt timeout của HTTP client ít nhất là `120s`. Nếu phản hồi tạo có `status: "pending"`, `task_id`, hoặc `poll_url`, hãy theo `poll_url` được trả về để polling.

<ParamField body="image" type="file" required>
  Hình ảnh dùng làm cơ sở cho biến thể. Phải là file PNG hợp lệ, nhỏ hơn 50MB và có tỷ lệ vuông.
</ParamField>

<ParamField body="model" type="string" required>
  ID model bắt buộc cho các route legacy tương thích biến thể. Không có default ngầm định; với workflow image-to-image hiện tại, ưu tiên `/v1/images/edits` hoặc `/v1/images/generations` với model hiện tại.
</ParamField>

<ParamField body="n" type="integer" default="1">
  Số lượng hình ảnh cần tạo. Phải từ 1 đến 10.
</ParamField>

<ParamField body="size" type="string">
  Kích thước ảnh được tạo cho các route legacy tương thích biến thể. Giá trị hỗ trợ phụ thuộc vào model đã chọn.
</ParamField>

<ParamField body="response_format" type="string" default="url">
  Định dạng trả về của hình ảnh được tạo. Phải là `url` hoặc `b64_json`.
</ParamField>

<ParamField body="user" type="string">
  Mã định danh duy nhất đại diện cho người dùng cuối để giám sát lạm dụng.
</ParamField>

## Phản hồi

<ResponseField name="created" type="integer">
  Dấu thời gian Unix khi hình ảnh được tạo.
</ResponseField>

<ResponseField name="data" type="array">
  Mảng các biến thể hình ảnh đã tạo.

  Mỗi đối tượng chứa:

  * `url` (string): URL của hình ảnh biến thể (nếu response\_format là `url`)
  * `b64_json` (string): Hình ảnh mã hóa Base64 (nếu response\_format là `b64_json`)
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.tokenlab.sh/v1/images/variations" \
    -H "Authorization: Bearer sk-your-api-key" \
    -F "model=your-legacy-variation-model" \
    -F "image=@cat.png" \
    -F "n=2" \
    -F "size=1024x1024"
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-your-api-key",
      base_url="https://api.tokenlab.sh/v1"
  )

  response = client.images.create_variation(
      model="your-legacy-variation-model",
      image=open("cat.png", "rb"),
      n=2,
      size="1024x1024"
  )

  for image in response.data:
      print(image.url)
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from 'openai';
  import fs from 'fs';

  const client = new OpenAI({
    apiKey: 'sk-your-api-key',
    baseURL: 'https://api.tokenlab.sh/v1'
  });

  const response = await client.images.createVariation({
    model: 'your-legacy-variation-model',
    image: fs.createReadStream('cat.png'),
    n: 2,
    size: '1024x1024'
  });

  response.data.forEach(image => console.log(image.url));
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "fmt"
      "io"
      "mime/multipart"
      "net/http"
      "os"
  )

  func main() {
      body := &bytes.Buffer{}
      writer := multipart.NewWriter(body)

      writer.WriteField("model", "your-legacy-variation-model")

      file, _ := os.Open("cat.png")
      defer file.Close()
      part, _ := writer.CreateFormFile("image", "cat.png")
      io.Copy(part, file)

      writer.WriteField("n", "2")
      writer.WriteField("size", "1024x1024")
      writer.Close()

      req, _ := http.NewRequest("POST", "https://api.tokenlab.sh/v1/images/variations", body)
      req.Header.Set("Authorization", "Bearer sk-your-api-key")
      req.Header.Set("Content-Type", writer.FormDataContentType())

      client := &http.Client{}
      resp, _ := client.Do(req)
      defer resp.Body.Close()

      result, _ := io.ReadAll(resp.Body)
      fmt.Println(string(result))
  }
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://api.tokenlab.sh/v1/images/variations');

  $image = new CURLFile('cat.png', 'image/png', 'cat.png');

  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer sk-your-api-key'
      ],
      CURLOPT_POSTFIELDS => [
          'model' => 'your-legacy-variation-model',
          'image' => $image,
          'n' => 2,
          'size' => '1024x1024'
      ]
  ]);

  $response = curl_exec($ch);
  curl_close($ch);

  $data = json_decode($response, true);
  foreach ($data['data'] as $image) {
      echo $image['url'] . "\n";
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Phản hồi theme={null}
  {
    "created": 1706000000,
    "data": [
      {
        "url": "https://..."
      },
      {
        "url": "https://..."
      }
    ]
  }
  ```
</ResponseExample>

## Ghi chú

<Note>
  Đây là endpoint tương thích legacy. Endpoint này không nằm trong catalog model ảnh được khuyến nghị hiện tại. Với tích hợp mới, dùng `/v1/images/edits` với `gpt-image-2`, hoặc `/v1/images/generations` với `operation: "image-to-image"` và một model image-to-image hiện tại.
</Note>