Gerar imagens

POST /v1/images/generations

Gera imagens. Síncrono por predefinição: a chamada espera até a imagem estar pronta e responde com a mesma estrutura do endpoint images/generations da OpenAI, pelo que o SDK da OpenAI e os gateways de reencaminhamento funcionam tal como estão. Com async: true recebes de imediato um id de tarefa e lês o resultado em GET /v1/tasks/{id}. Com n maior que 1 são criadas n tarefas independentes, cada uma faturada em separado.

Parâmetros

Parâmetro	Tipo	Descrição
prompt	string	Obrigatório. O que desenhar
model	string	id de modelo de /v1/models. Sem ele, o modelo predefinido
n	integer	Número de imagens, de 1 a 4. Predefinição 1
size	string	Proporção 1:1 \| 16:9 \| 9:16 \| 4:3 \| 3:4. Predefinição 1:1. Também aceita formatos em píxeis como 1024x1024 ou 1792x1024, ajustados à proporção mais próxima
quality	string	Qualidade 1k \| 2k \| 4k. Predefinição 1k; spec tem prioridade. Também aceita a nomenclatura da OpenAI: standard / low / auto valem 1k e medium / hd / high valem 2k
spec	string	Chave de nível retirada de specs[].key do modelo
reference_images	string[]	URLs de referência. O que exceder max_reference_images é descartado
async	boolean	Predefinição false: espera pela imagem. Com true devolve logo um objeto de tarefa e sondas /v1/tasks/{id} por tua conta

Valores não reconhecidos não fazem o pedido falhar: volta-se à predefinição (um size desconhecido é simplesmente gerado em 1:1). Só dão erro um prompt vazio, conteúdo bloqueado, um limite atingido ou créditos insuficientes. response_format não é suportado: os resultados chegam sempre como url.

Pedido (síncrono)

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "uma rua cyberpunk à chuva de noite, reflexos de néon",
    "size": "16:9",
    "quality": "2k",
    "n": 1
  }'

Resposta (síncrona)

json

{
  "created": 1786000246,
  "data": [
    { "url": "https://cdn.pikpikgo.com/ai/xxxx.png", "revised_prompt": "uma rua cyberpunk à chuva de noite, reflexos de néon" }
  ],
  "id": "2608101909450810293847",
  "object": "image.generation",
  "model": "img-std-1",
  "status": "succeeded",
  "n": 1,
  "credits": 10,
  "tasks": [
    {
      "id": "2608101909450810293847",
      "status": "succeeded",
      "data": [{ "url": "https://cdn.pikpikgo.com/ai/xxxx.png", "revised_prompt": "uma rua cyberpunk à chuva de noite, reflexos de néon" }]
    }
  ]
}

Campo	Descrição
created	Marca temporal da resposta
data	Resultados, cada um com url e revised_prompt. Vários quando n > 1
id	Tarefa principal (com n > 1, a primeira subtarefa)
status	succeeded, mesmo em sucesso parcial: compara tu o tamanho de data com n
credits	Total de créditos debitados
tasks	Todas as subtarefas, cada uma com o seu error e resultado

Uma chamada síncrona mantém a ligação aberta, muitas vezes mais de 30 segundos por imagem: alarga o tempo limite do cliente para 300 segundos. Passados 300 segundos o servidor devolve 504 generation_timeout; a tarefa continua e os créditos não são devolvidos, por isso vai buscar o resultado mais tarde a /v1/tasks/{id} com o id que vem na mensagem. Se falharem todas as imagens obténs 502 generation_failed e os créditos são devolvidos automaticamente.

Fluxo assíncrono

Para lotes, muita concorrência ou clientes sensíveis à latência: a resposta chega logo, com status queued e data vazio.

bash

curl https://open.pikpikgo.com/v1/images/generations \
  -H "Authorization: Bearer $PIKPIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "uma rua cyberpunk à chuva de noite, reflexos de néon",
    "size": "16:9",
    "quality": "2k",
    "n": 1,
    "async": true
  }'

json

{
  "id": "2608101909450810293847",
  "object": "image.generation",
  "created": 1786000185,
  "model": "img-std-1",
  "status": "queued",
  "n": 1,
  "credits": 10,
  "tasks": [
    { "id": "2608101909450810293847", "status": "queued", "data": [] }
  ],
  "data": []
}

Com n > 1 percorre tasks. Consultar apenas id perde silenciosamente as restantes imagens.