Saltar para o conteúdo principal
O serviço de edição de imagens da OpenAI permite enviar várias imagens e instruções, gerando imagens modificadas. Este documento descreve principalmente o fluxo de uso da API OpenAI Images Edits, permitindo que utilizemos facilmente a funcionalidade de edição de imagens oficial da OpenAI.

​
Processo de Solicitação

Para usar a API OpenAI Images Edits, primeiro você pode acessar a página OpenAI Images Edits API e clicar no botão “Acquire” para obter as credenciais necessárias para a solicitação: Se você ainda não estiver logado ou registrado, será redirecionado automaticamente para a página de login, convidando-o a se registrar e fazer login. Após o login ou registro, você será redirecionado de volta para a página atual. Na primeira solicitação, haverá um crédito gratuito disponível, permitindo o uso gratuito dessa API.

​
Uso Básico

Em seguida, você pode usar o código para fazer a chamada. Abaixo está um exemplo de chamada usando 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'
Na primeira vez que você usar essa interface, precisará preencher pelo menos quatro informações: uma é authorization, que pode ser selecionada diretamente na lista suspensa. Outro parâmetro é model, que é a categoria do modelo que escolhemos usar no site da OpenAI. Aqui temos principalmente 1 modelo, e mais detalhes podem ser encontrados nos modelos que fornecemos. Outro parâmetro é prompt, que é a palavra-chave que inserimos para gerar a imagem. O último parâmetro é image, que precisa ser o caminho da imagem a ser editada, conforme mostrado na imagem abaixo:

Código de exemplo em Python com o mesmo efeito de chamada: 
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)

# Save the image to a file
with open("gift-basket.png", "wb") as f:
    f.write(image_bytes)
Para usar a chamada em Python, precisamos primeiro importar duas variáveis de ambiente: uma OPENAI_BASE_URL, que pode ser configurada como https://api.acedata.cloud/openai, e outra variável de credencial OPENAI_API_KEY, cujo valor é obtido a partir da authorization. No Mac OS, você pode definir as variáveis de ambiente com os seguintes comandos: 
export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token}
Após a chamada, você verá que uma imagem gift-basket.png será gerada no diretório atual, e o resultado específico é o seguinte:

Assim, completamos a operação de edição de imagem. Atualmente, a tarefa Edits oficial suporta apenas dois modelos: dall-e-2 e gpt-image-1.

​
Callback Assíncrono

Como o tempo de edição de imagens da API OpenAI Images Edits pode ser relativamente longo, se a API não responder por um longo período, a solicitação HTTP manterá a conexão, resultando em consumo adicional de recursos do sistema. Portanto, esta API também oferece suporte a callbacks assíncronos. O fluxo geral é: quando o cliente inicia a solicitação, deve especificar um campo callback_url. Após a solicitação da API, a API retornará imediatamente um resultado, incluindo um campo task_id, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado da edição da imagem será enviado para o callback_url especificado pelo cliente em formato JSON POST, incluindo também o campo task_id, permitindo que o resultado da tarefa seja associado pelo ID. Vamos entender como operar isso através de um exemplo. Primeiro, o callback Webhook é um serviço que pode receber solicitações HTTP. O desenvolvedor deve substituir pelo URL do servidor HTTP que ele configurou. Para facilitar a demonstração, usaremos um site de exemplo de Webhook público https://webhook.site/, onde você pode abrir o site e obter um URL de Webhook, conforme mostrado na imagem: Copie este URL para usá-lo como Webhook. O exemplo aqui é https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab. Em seguida, podemos definir o campo callback_url para o URL do Webhook acima, enquanto preenchemos os parâmetros correspondentes, como mostrado no código abaixo: 
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"
Após a chamada, você receberá imediatamente um resultado, como abaixo: 
{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}
Após alguns instantes, você poderá observar o resultado da edição da imagem no URL do Webhook, conforme o conteúdo abaixo: 
{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": {
    "created": 1721626477,
    "data": [
      {
        "b64_json": "iVBORw0KGgo..."
      }
    ]
  }
}
Você pode ver que o resultado contém um campo task_id, e o campo data inclui o mesmo resultado de edição de imagem que a chamada síncrona. O campo task_id permite a associação da tarefa.

​
Tratamento de Erros

Ao chamar a API, se ocorrer um erro, a API retornará o código e a mensagem de erro correspondentes. Por exemplo:
  • 400 token_mismatched: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
  • 400 api_not_implemented: Solicitação inválida, possivelmente devido a parâmetros ausentes ou inválidos.
  • 401 invalid_token: Não autorizado, token de autorização inválido ou ausente.
  • 429 too_many_requests: Muitas solicitações, você excedeu o limite de taxa.
  • 500 api_error: Erro interno do servidor, algo deu errado no servidor.

​
Exemplo de Resposta de Erro

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

​
Conclusão

Através deste documento, você já entendeu como usar a API de Edição de Imagens da OpenAI para utilizar facilmente as funcionalidades de edição de imagens oficiais da OpenAI. Esperamos que este documento possa ajudá-lo a integrar e usar melhor essa API. Se tiver alguma dúvida, sinta-se à vontade para entrar em contato com nossa equipe de suporte técnico.