aisplice

Referência da API

Imagens: tarefas assíncronas

Modelos deste endpoint (12)

gpt-image-2.5-extgpt-image-2seedream-5-0-flashgpt-image-2.5-flare+8
Experimente no Workbench
POST/v1/images/tasks
GET/v1/images/tasks/{task_id}
GET/v1/images/tasks/{task_id}/content

Geração de imagens assíncrona — a rota usada por todos os modelos de imagem do catálogo. O envio retorna um task_id; consulte o endpoint de status e depois leia as URLs persistentes do resultado em /content — ou registre um webhook e dispense as consultas.

#Parâmetros da requisição

  • modelstringobrigatório

    ID de um modelo de imagem assíncrono, por exemplo gpt-image-2. Modelos só síncronos rejeitam este endpoint.

  • promptstringobrigatório

    O que desenhar.

  • sizestringopcional

    Proporção predefinida como "16:9" — o formato que a maioria dos modelos de imagem usa; os valores exatos estão na ficha do modelo. Alguns modelos mais antigos também aceitam WIDTHxHEIGHT.

  • resolutionstringopcional

    Faixa de resolução da saída como "1K", "2K" ou "4K", quando a ficha do modelo a lista — também uma dimensão da faixa de preço.

  • qualitystringopcional

    Nível de qualidade do provedor (por exemplo, standard / hd) — também uma dimensão da faixa de preço.

  • nintegeropcional

    Número de imagens (a cobrança é multiplicada por imagem).

  • imagesarrayopcional

    Imagens de referência para editar ou seguir, como URLs ou data URIs. A ficha do modelo mostra quantas cada modelo aceita.

  • maskstringopcional

    Redesenha uma área da primeira imagem de referência — veja "Editar parte de uma imagem" abaixo. Só os modelos cuja ficha lista mask aceitam; mask_url é aceito como o mesmo campo.

  • webhook_urlstringopcional

    URL HTTPS chamada quando a tarefa chega a um estado final — veja o guia de vídeo para o contrato do callback.

  • webhook_secretstringopcional

    Se definido, as entregas trazem X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret)).

Os parâmetros variam por modelo

Confira na ficha do modelo quais campos e valores cada modelo aceita. O gpt-image-2.5-ext recebe size como proporção mais resolution; um tamanho em pixels como 2560x1088 é convertido para a proporção e a resolução mais próximas (21:9 em 2K). Ele não tem controle de background: "auto" é ignorado e outros valores são rejeitados. Ele gera uma imagem por requisição e não permite escolher version: deixe de fora ou envie "flare".

Os nomes de campos podem variar por família de modelos

Os payloads de status da tarefa refletem o que o provedor upstream informa; considere as respostas reais como referência e use task_id, status e o endpoint /content, que são estáveis entre provedores.

#Editar parte de uma imagem

Envie a imagem em images e uma mask: só a área mascarada é redesenhada e o resto da imagem fica como está. Diga em prompt o que deve aparecer ali. Hoje aceitam máscara o gpt-image-2.5-flare e o gpt-image-2.5-sunburst; a ficha do modelo a mostra como o campo mask.

curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "Replace the mug with a glass of orange juice; keep everything else",
    "images": ["https://example.com/desk.png"],
    "mask": "https://example.com/desk-mask.png",
    "resolution": "1K"
  }'

Como fazer a máscara

Um PNG com canal alfa: os pixels totalmente transparentes marcam a área a redesenhar, e o resto é mantido. Ele precisa ter exatamente o tamanho em pixels da primeira imagem de referência (não o da saída) e menos de 4 MB. Uma máscara por requisição; com várias imagens de referência, ela vale para a primeira. Nos modelos gpt-image-2.5, deixe size de fora para o resultado manter a proporção da imagem.
  • 400 invalid_requestmask foi enviado sem imagem de referência, ou para um modelo que não aceita máscara (o gpt-image-2.5-ext responde "mask is not supported on Ext").

Tabela completa de códigos de erro →

#Erros relacionados

  • 404 not_foundCaminho desconhecido, nome de modelo desconhecido ou um task_id expirado ou de outra conta.
  • 401Bearer token inválido ou ausente. Não há error.code neste caminho — verifique o status.
  • 402 insufficient_user_quotaO saldo da carteira não cobre a estimativa pré-reservada.
  • 429Limitação por chave. Corpo vazio; aguarde o Retry-After. Um 429 que traz insufficient_user_quota indica, na verdade, o limite de gastos diário.
  • 503 model_not_foundModelo desconhecido, ou nenhum canal saudável o atende no momento.

Tabela completa de códigos de erro →

#Exemplo de requisição

# 1. submit
curl https://www.aisplice.store/v1/images/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.5-ext", "prompt": "A red paper crane on a desk", "size": "16:9", "resolution": "1K"}'

# 2. poll every 3s until a terminal status
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# 3. fetch persistent result URLs
curl https://www.aisplice.store/v1/images/tasks/$TASK_ID/content -H "Authorization: Bearer sk-YOUR_KEY"

#Resposta

response.json
// POST /v1/images/tasks
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/images/tasks/{task_id}
{"task_id": "task_xxx", "status": "in_progress", "progress": "60%"}

// GET /v1/images/tasks/{task_id}/content — after completion
{"created": 1720000000, "data": [{"url": "https://…"}]}

Ainda com problemas?

Envie para nós o ID da requisição ou a mensagem de erro e vamos investigar.

AnteriorMessages (formato Anthropic)PróximoVídeos