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

# Nano Banana Images API Integrationsbeskrivning

> Nano Banana Image Generation 集成指南 - XHuoAPI

Denna artikel beskriver integration och användning av Nano Banana Images API. Detta gränssnitt stöder två funktioner: **bildgenerering (generate)** och **billedredigering (edit)**.

## Ansökningsprocess

Innan användning, vänligen gå till [Nano Banana Images API](https://api.xhuoapi.ai/documents/23985a11-d713-41d1-ad84-24b021805b3d) på XHuoAPI-plattformen och klicka på Acquire för att ansöka om aktivering. Första gången du ansöker finns det vanligtvis en gratis kvot tillgänglig. När aktiveringen är klar kan du hämta Bearer Token som används för att anropa API:et.

## Gränssnittsöversikt

* **Bas-URL**: `https://api.xhuoapi.ai/v1`
* **Endpoint**: `POST /nano-banana/images`
* **Autentisering**: HTTP-headern innehåller `authorization: Bearer {token}`
* **Begärningshuvud**:
  * `accept: application/json`
  * `content-type: application/json`
* **Åtgärd (action)**:
  * `generate`: Generera bilder baserat på textprompt
  * `edit`: Redigera baserat på angiven bild
* **Modell (model)** (valfritt):
  * `nano-banana` (standard): Baserad på Gemini 2.5 Flash Image, snabb hastighet, låg kostnad
  * `nano-banana-2`: Baserad på Gemini 3.1 Flash Image Preview, Pro-kvalitet + Flash-hastighet
  * `nano-banana-pro`: Baserad på Gemini 3 Pro Image Preview, högsta kvalitet
* **Asynkron callback**: Valfritt, ta emot meddelande om uppgiftens slutförande och resultat via `callback_url`

## Snabbstart: Generera bild (`action=generate`)

**Minimala nödvändiga parametrar**: `action`, `prompt`
När du bara vill generera en bild baserat på en prompt, ställ in `action` till `generate` och ge en tydlig `prompt`.

### Begärningsexempel (cURL)

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "generate",
    "prompt": "Ett fotorealistiskt närbildsporträtt av en gammal japansk keramiker med djupa, sol-etsade rynkor och ett varmt, vetande leende. Han inspekterar noggrant en nyglaserad tekopp. Miljön är hans rustika, solbelysta verkstad. Scenen är belyst av mjukt, gyllene timmesljus som strömmar genom ett fönster och framhäver den fina texturen av leran. Fångad med en 85 mm porträttlins, vilket resulterar i en mjuk, suddig bakgrund (bokeh). Den övergripande stämningen är lugn och mästerlig. Vertikal porträttorientering.",
    "count": 1
  }'
```

### Begärningsexempel (Python)

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "generate",
    "prompt": (
        "Ett fotorealistiskt närbildsporträtt av en gammal japansk keramiker "
        "med djupa, sol-etsade rynkor och ett varmt, vetande leende. Han inspekterar noggrant "
        "en nyglaserad tekopp. Miljön är hans rustika, solbelysta verkstad. Scenen är belyst "
        "av mjukt, gyllene timmesljus som strömmar genom ett fönster och framhäver den fina "
        "texturen av leran. Fångad med en 85 mm porträttlins, vilket resulterar i en mjuk, "
        "suddig bakgrund (bokeh). Den övergripande stämningen är lugn och mästerlig. Vertikal "
        "porträttorientering."
    ),
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())
```

### Framgångsrik retur exempel

```json theme={null}
{
  "success": true,
  "task_id": "056f0589-a3dd-4ec2-8440-ad61f5038dfa",
  "trace_id": "c48de83f-0077-426e-b02b-ff1d58179064",
  "data": [
    {
      "prompt": "Ett fotorealistiskt närbildsporträtt av en gammal japansk keramiker med djupa, sol-etsade rynkor och ett varmt, vetande leende. Han inspekterar noggrant en nyglaserad tekopp. Miljön är hans rustika, solbelysta verkstad. Scenen är belyst av mjukt, gyllene timmesljus som strömmar genom ett fönster och framhäver den fina texturen av leran. Fångad med en 85 mm porträttlins, vilket resulterar i en mjuk, suddig bakgrund (bokeh). Den övergripande stämningen är lugn och mästerlig. Vertikal porträttorientering.",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/69790adb-c85d-4362-ad9e-0c9ba4352cf4.png"
    }
  ]
}
```

### Fältbeskrivning

* `success`: Om denna begäran var framgångsrik.
* `task_id`: Uppgiftens ID.
* `trace_id`: Spårnings-ID, för att underlätta felsökning.
* `data[]`: Resultatlista.
  * `prompt`: Används för att generera prompt (återkoppling).
  * `image_url`: Direktlänk URL till den genererade bilden.

> Obs: `/nano-banana/images` kräver endast `action` och `prompt` för att generera en bild

## Redigera bild (`action=edit`)

När du vill redigera baserat på en befintlig bild, ställ in `action` till `edit` och skicka in en lista med länkar till bilder som ska redigeras via `image_urls` (1 eller flera), samtidigt som du ger en beskrivning av redigeringsmålet med `prompt`.

Till exempel, här kan vi ge en bild av en person och en bild av en tröja, så att personen kan ha på sig den tröjan, och vi kan skicka in bildlänkarna och ange action som `edit`. URL:er kan vara HTTP-URL:er, offentligt tillgängliga länkar med `https` eller `http` protokoll, eller så kan de vara Base64-kodade bilder, som `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA+gAAAVGCAMAAAA6u2FyAAADAFBMVEXq6uwdHCEeHyMdHS....`

### Begärningsexempel (cURL)

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/nano-banana/images' \
  -H 'authorization: Bearer {token}' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
    "action": "edit",
    "prompt": "låt denna man ha på sig denna T-shirt",
    "image_urls": [
      "https://cdn.xhuoapi.ai/v8073y.png",
      "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
  }'
```

### Begärningsexempel (Python)

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/nano-banana/images"
headers = {
    "authorization": "Bearer {token}",
    "accept": "application/json",
    "content-type": "application/json",
}
payload = {
    "action": "edit",
    "prompt": "låt denna man ha på sig denna T-shirt",
    "image_urls": [
        "https://cdn.xhuoapi.ai/v8073y.png",
        "https://cdn.xhuoapi.ai/44xlah.png"
    ],
    "count": 1
}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json())
```

### Framgångsrik retur exempel

```json theme={null}
{
  "success": true,
  "task_id": "93f11baf-347b-4bb4-9520-8653cb46d6a3",
  "trace_id": "a9063166-26ed-4451-85b5-54e896817c69",
  "data": [
    {
      "prompt": "låt denna man ha på sig denna T-shirt",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/8e9e0253-26f4-45b9-b3f8-ac1aed1c284b.png"
    }
  ]
}
```

### Fältbeskrivning

* `image_urls[]`: Lista över URL:er till bilder som ska redigeras (måste vara offentligt tillgängliga). Flera bilder kan skickas, tjänsten kommer att kombinera dessa material med `prompt` för att slutföra redigeringen.
* Övriga fält är desamma som för "generera bild" retur.

***

## Asynkron callback (valfritt, rekommenderas)

Generering eller redigering kan ta viss tid. För att undvika att långvariga anslutningar upptar resurser, rekommenderas att använda **Webhook callback** via `callback_url`:

1. Lägg till `callback_url` i begärningskroppen, till exempel din server Webhook-adress (måste vara offentligt tillgänglig, stödja POST JSON).
2. API:et kommer att **omedelbart returnera** ett svar som innehåller `task_id` (eller grundläggande resultat).
3. När uppgiften är klar kommer plattformen att skicka den fullständiga JSON:en till `callback_url` med `POST`-metoden. Du kan koppla begäran till resultatet med `task_id`.

**Exempel på callback-last** (fältstrukturen är densamma som för synkron framgångsrik återkoppling):

```json theme={null}
{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": [
    {
      "prompt": "en vit siamesisk katt",
      "image_url": "https://platform.cdn.xhuoapi.ai/nanobanana/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png"
    }
  ]
}
```

***

## Felhantering

Vid misslyckad anrop kommer standardfelformat och spårnings-ID att returneras. Vanliga fel är följande:

* **400 `token_mismatched`**: Begäran är ogiltig eller parameterfel.
* **400 `api_not_implemented`**: Gränssnittet är inte implementerat (vänligen kontakta support).
* **401 `invalid_token`**: Autentisering misslyckades eller saknar token.
* **429 `too_many_requests`**: Begärningsfrekvensen överskrider gränsen.
* **500 `api_error`**: Serverfel.

### Exempel på felrespons

```json theme={null}
{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "Intern serverfel."
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```

***

## Parameteröversikt och viktiga punkter

* **Obligatoriska**: `action`, `prompt`
* **Redigeringsspecifik**: `image_urls` (array, minst 1 post)
* **Valfritt**: `model` (standard `nano-banana`, valfritt `nano-banana-2` eller `nano-banana-pro`), `aspect_ratio` (bredd-höjd-förhållande, som `1:1`, `16:9`), `resolution` (upplösning, som `1K`, `2K`, `4K`), `callback_url` (för asynkron callback)
* **Headers**: Måste ange `authorization: Bearer {token}`; `accept` rekommenderas att sättas till `application/json`
* **Tillgänglighet för bilder**: `image_urls` måste vara direktlänkar som är offentligt tillgängliga (HTTP/HTTPS), rekommenderas att använda HTTPS
* **Idempotens och spårning**: Bevara `task_id` och `trace_id` för att underlätta felsökning och koppling av resultat