OpenAI Images Edits API Ansökan och Användning

OpenAI generation 集成指南 - Ace Data Cloud

OpenAI bildredigeringstjänst låter dig skicka in valfritt antal bilder och instruktioner för att få redigerade bilder som resultat. För närvarande stöder API:et samtidigt dall-e-2, gpt-image-1, den senaste gpt-image-2, samt modellerna i nano-banana / nano-banana-2 / nano-banana-pro serien som ansluts via samma gränssnitt.

Detta dokument beskriver huvudsakligen användningsflödet för OpenAI Images Edits API, vilket gör det enkelt att använda den officiella OpenAI bildredigeringsfunktionen.

​

Ansökningsprocess

För att använda OpenAI Images Edits API kan du först gå till sidan OpenAI Images Edits API och klicka på knappen “Acquire” för att få de autentiseringsuppgifter som krävs för förfrågningar:

Om du inte är inloggad eller registrerad kommer du automatiskt att omdirigeras till inloggningssidan för att registrera dig och logga in. Efter inloggning eller registrering återvänder du automatiskt till den aktuella sidan.

Vid första ansökan får du en gratis kvot som gör att du kan använda API:et kostnadsfritt.

​

GPT-Image-2 Modell

gpt-image-2 har en mycket tydlig förbättring jämfört med gpt-image-1 i bildredigeringsscenarier:

• Mer stabil struktur: Vid byte av hud, färgschema eller bakgrund förstörs nästan aldrig originalbildens layout eller komposition.
• Mer exakt textbevarande: Bilder med text, som informationsgrafik, affischer och menyer, behåller tydlig och läsbar text efter redigering.
• Stöd för direkt URL-överföring: Förutom traditionell filuppladdning via multipart/form-data stöder gpt-image-2 även att skicka bild-URL:er i JSON-format, vilket eliminerar behovet av att först ladda ner bilden lokalt. Detta är mycket lämpligt för serverbaserade pipeline-integrationer.
• Stöd för högupplöst omritning: Du kan skicka in en 1K originalbild och med size-parametern begära 2K eller 4K output, där modellen samtidigt skalar upp bilden under redigeringsprocessen.

​

Stödda size-värden

Redigeringsgränssnittets begränsningar för size är helt samma som för genereringsgränssnittet — gpt-image-2 accepterar endast size som auto, tomt, eller i formatet WIDTHxHEIGHT. Alla andra format returnerar 400. Alla storlekar (1K / 2K / 4K / anpassade) debiteras per bild oberoende av originalbildens upplösning eller size-värdet.

Upstream har samma hårda begränsningar för anpassade storlekar: bredd och höjd måste vara multiplar av 16, längsta sidan ≤ 3840, och totalt antal pixlar ≤ 8,294,400.

Proportion	1K Rekommenderat	2K Rekommenderat	4K Rekommenderat
1:1	1024x1024	2048x2048	2880x2880
4:3	1536x1024	2048x1536	3264x2448
3:4	1024x1536	1536x2048	2448x3264
16:9	1792x1024	2048x1152	3840x2160
9:16	1024x1792	1152x2048	2160x3840

Exempel: Om originalbilden är 1024x1024 och size sätts till 2048x2048, kommer modellen att rita om och leverera en 2K-bild enligt redigeringsinstruktionerna; size 3840x2160 ger en 4K liggande bild; auto eller inget värde låter modellen själv välja. Alla tre debiteras lika.

Om n-parametern

gpt-image-2 redigerings-API stöder för närvarande inte n > 1: denna parameter ignoreras tyst, oavsett om du skickar n=1 eller n=10 returneras endast en bild per förfrågan och debiteras som en. Om du behöver flera redigeringsresultat samtidigt, vänligen gör flera parallella förfrågningar. Denna begränsning gäller även för gpt-image-1 / gpt-image-1.5 samt nano-banana / nano-banana-2 / nano-banana-pro modellerna. dall-e-2 är för närvarande den enda redigeringsmodellen som inbyggt stödjer n > 1.

Nedan visas två verkliga exempel från olika perspektiv för att visa gpt-image-2 redigeringsförmåga.

​

Anropsmetod 1: JSON + Bild-URL (rekommenderas)

Skicka förfrågan direkt som application/json och fyll i image-fältet med en bild-URL. Modellen hämtar bilden och redigerar enligt prompt.

Till exempel, denna originalbild är en vetenskaplig infographic genererad med gpt-image-2:

Vi vill ändra den till “nattläge” färgschema. Så här kan du anropa:

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
  }'

Eller med Python:

import requests

url = "https://api.acedata.cloud/openai/images/edits"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

Svarsexempel:

{
  "success": true,
  "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753",
  "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8",
  "created": 1777048863,
  "data": [
    {
      "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
      "url": "https://platform.cdn.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png"
    }
  ],
  "elapsed": 83.859
}

Den redigerade bilden:

Man kan se att modulstrukturen, informationsavdelningarna och typografin är strikt bevarade, endast färgschemat har inverterats till ett mörkt tema.

Tips: image-fältet kan också ta en array, t.ex. "image": ["url1", "url2", "url3"], upp till 16 referensbilder samtidigt för att låta modellen göra en samlad redigering baserat på flera bilder.

​

Anropsmetod 2: JSON + flera referensbilder

gpt-image-2 kan samtidigt referera till flera bilder för att generera slutresultatet, t.ex. kombinera flera produktbilder till en presentkorg:

payload = {
    "model": "gpt-image-2",
    "image": [
        "https://example.com/item1.png",
        "https://example.com/item2.png",
        "https://example.com/item3.png"
    ],
    "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.",
    "size": "1024x1024"
}

​

Scenarieexempel: Byt stil + behåll struktur

Här är ett annat exempel där en träbokhylla ersätts med en modern flytande hylla, men antalet och arrangemanget av böcker på varje hyllplan bevaras strikt.

Originalbild (träbokhylla genererad med gpt-image-2):

Anrop:

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png",
    "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.",
    "size": "1024x1024"
}

Redigeringsresultat (task_id: e9544dba-727e-44a2-81e1-223d49869380):

Man kan se att stil och miljö har bytts helt enligt prompten, men antalet böcker på varje hyllplan (1 / 3 / 7) är strikt bevarat och en liten suckulent har lagts till enligt instruktion.

​

Anropsmetod 3: multipart/form-data (kompatibelt med OpenAI SDK)

Om du redan använder officiella OpenAI Python SDK fungerar den traditionella multipart/form-data-uppladdningen också, bara ändra model till gpt-image-2:

import base64
from openai import OpenAI
client = OpenAI()

result = client.images.edit(
    model="gpt-image-2",
    image=[open("test.png", "rb")],
    prompt="Convert this image to dark mode while keeping the layout intact."
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)
with open("edited.png", "wb") as f:
    f.write(image_bytes)

Vid användning av SDK måste du först exportera två miljövariabler, OPENAI_BASE_URL sätts till https://api.acedata.cloud/openai och OPENAI_API_KEY sätts till den token du fått:

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token}

​

Nano Banana Serie Modeller

nano-banana serien är också ansluten till /openai/images/edits för redigeringsscenarier. Byt bara model till någon av nedanstående för att använda:

Modell	Kostnad (Credits / gång)	Användningsområde
nano-banana	0.14	Vanlig bildredigering, snabbast och billigast
nano-banana-2	0.28	Märkbart förbättrad kvalitet och detaljrikedom
nano-banana-pro	0.35	Flaggskepp i serien, bäst bevarande av struktur, text och stil

Viktigt: Stödda parametrar

Nano Banana är ansluten via en adapter till OpenAI-protokollet och stöder endast följande parametrar: model, prompt, image.

• image kan skickas som fil via multipart/form-data (omvandlas internt till data:<mime>;base64,... för upstream) eller som URL-sträng direkt i formulärfältet.
• Stöder inte mask, n, size, response_format etc.; dessa ignoreras om de skickas.
• Returdata följer OpenAI-formatet (data[].url), men created är alltid 0, och b64_json returneras aldrig. revised_prompt är alltid samma som original prompt.

​

Anropa via formulär + bild-URL

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=nano-banana" \
  -F "prompt=add a green leaf on top of the apple" \
  -F "image=https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png"

Exempel på svar:

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg",
      "revised_prompt": "add a green leaf on top of the apple"
    }
  ]
}

Redigerad bild:

​

Anropa via formulär + lokal fil

import requests

url = "https://api.acedata.cloud/openai/images/edits"

headers = {
    "authorization": "Bearer {token}"
}

files = {
    "image": open("apple.png", "rb"),
}
data = {
    "model": "nano-banana-pro",
    "prompt": "add a green leaf on top of the apple"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.text)

​

Asynkron callback

callback_url asynkron callback-mekanism fungerar även för nano-banana, och anropsflödet är helt identiskt med andra modeller. Se avsnittet Asynkron callback nedan.

​

Grundläggande användning

Härnäst kan du använda kod för att anropa API:et. Nedan är ett exempel med CURL:

curl -s -D >(grep -i x-request-id >&2) \
  -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \
  -X POST "https://api.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -F 'prompt=Create a lovely gift basket with these this items in it'

Vid första användningen av detta API behöver vi fylla i minst fyra saker: en authorization som väljs från en dropdown, en model som anger vilken OpenAI-modell vi vill använda (här finns huvudsakligen en modell, se våra modellbeskrivningar), en prompt som är textinstruktionen för bildgenerering, och slutligen image som är sökvägen till bilden som ska redigeras. Exempelbilden visas nedan:

Samma anrop i Python:

import base64
from openai import OpenAI
client = OpenAI()

prompt = """
Generate a photorealistic image of a gift basket on a white background 
labeled 'Relax & Unwind' with a ribbon and handwriting-like font, 
containing all the items in the reference pictures.
"""

result = client.images.edit(
    model="gpt-image-1",
    image=[
        open("test.png", "rb")
    ],
    prompt=prompt
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

# Spara bilden till fil
with open("gift-basket.png", "wb") as f:
    f.write(image_bytes)

Vid Python-anrop behöver du först exportera två miljövariabler, OPENAI_BASE_URL som kan sättas till https://api.acedata.cloud/openai, samt OPENAI_API_KEY som är din token från authorization. På Mac OS kan du sätta dessa med:

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token} 

Efter anropet kommer en bildfil gift-basket.png att genereras i aktuell katalog. Resultatet ser ut så här:

Så har vi slutfört bildredigeringen. För närvarande stöder Edits API tre modeller: dall-e-2, gpt-image-1 och gpt-image-2, där gpt-image-2 är den rekommenderade modellen. Se avsnittet GPT-Image-2 Modell ovan för detaljer.

​

Asynkron callback

Eftersom redigering med OpenAI Images Edits API kan ta relativt lång tid, och om API:et inte svarar snabbt kan HTTP-anslutningen hållas öppen länge vilket belastar systemresurser, erbjuder API:et även stöd för asynkron callback.

Flödet är: klienten skickar en förfrågan och anger ett extra fält callback_url. API:et svarar omedelbart med ett svar som innehåller ett task_id som identifierar uppgiften. När redigeringen är klar skickas resultatet som en POST med JSON till den angivna callback_url, inklusive task_id, så att resultatet kan kopplas till rätt uppgift.

Nedan visas ett exempel på hur detta fungerar.

Först är webhook-callback en tjänst som kan ta emot HTTP-förfrågningar. Utvecklaren bör ersätta URL:en med sin egen HTTP-server. För demonstration används en offentlig webhook-tjänst https://webhook.site/ där du får en unik URL, som visas nedan:

Kopiera denna URL, t.ex. https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab, och använd som webhook.

Sedan kan vi ange fältet callback_url till denna URL och skicka med övriga parametrar, som i följande kod:

curl -X POST "https://api.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -F "prompt=Create a lovely gift basket with these items in it" \
  -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"

Efter anropet får du omedelbart ett svar som:

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

Efter en stund kan du se resultatet av bildredigeringen på webhook-URL:en, t.ex.:

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": {
    "created": 1721626477,
    "data": [
      {
        "b64_json": "iVBORw0KGgo..."
      }
    ]
  }
}

Man ser att resultatet innehåller ett task_id och data med samma bildredigeringsresultat som vid synkront anrop, vilket möjliggör koppling av uppgifter via task_id.

​

Felhantering

Vid API-anrop som resulterar i fel returnerar API:et motsvarande felkod och meddelande, till exempel:

• 400 token_mismatched: Felaktig förfrågan, troligen saknade eller ogiltiga parametrar.
• 400 api_not_implemented: Felaktig förfrågan, troligen saknade eller ogiltiga parametrar.
• 401 invalid_token: Obefogad, ogiltig eller saknad auktoriseringstoken.
• 429 too_many_requests: För många förfrågningar, du har överskridit hastighetsgränsen.
• 500 api_error: Intern serverfel, något gick fel på servern.

​

Exempel på felrespons

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​

Slutsats

Genom detta dokument har du fått en översikt över hur du enkelt använder OpenAI Images Edits API för att utnyttja officiella OpenAI:s bildredigeringsfunktioner. Vi hoppas att detta dokument hjälper dig att bättre integrera och använda API:et. Vid frågor är du välkommen att kontakta vårt tekniska supportteam.