JoyAI Image API

Documentação da API

Gere e edite imagens com uma API pública. Use joyai para edição por instruções, ou gptimage2 para text-to-image e edição com GPT Image 2.

Gerenciar chaves API Início rápido

Visão geral

Endpoint

/api/v1/generate

Um endpoint para modelos de imagem suportados. Comportamento via campo model.

Auth

Chaves API Bearer

Use chave API do painel no header Authorization. Chaves do servidor nunca vão ao navegador.

Async

Resultados por tarefa

A geração retorna um task ID. Consulte status para URLs finais.

Autenticação

Cada requisição exige chave API no header Authorization . Crie ou rotacione chaves em Painel > Chaves API.

Header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Modelos e créditos

model	Melhor para	Entrada de imagem	Créditos
`joyai`	Edição por instruções com 1 a 3 imagens de referência.	Sim, 1 a 3 URLs de imagem.	24 créditos por requisição.
`gptimage2`	Text-to-image e edição com GPT Image 2.	Opcional. Adicione imagens para modo edição.	Text: 2/4/6 low, 12/24/36 medium, 44/88/132 high para 1k/2k/4k. Edit: 6/12/18 low, 12/24/36 medium, 44/88/132 high para 1k/2k/4k.

Início rápido

Envie uma requisição para POST /api/v1/generate. A API retorna um task ID imediatamente; use GET /api/v1/status para consultar até sucesso ou falha.

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A premium product photo of a matte black espresso machine on a marble counter",
    "quality": "medium",
    "resolution": "1k",
    "aspect_ratio": "1:1"
  }'

POST /api/v1/generate

Cria tarefa de geração ou edição de imagem. Corpo JSON.

Parâmetros da requisição

Nome	Tipo	Obrigatório	Descrição
`model`	string	Sim	Use joyai ou gptimage2.
`prompt`	string	Sim	Instrução em linguagem natural. joyai até 1500 caracteres; gptimage2 até 20000.
`images`	string[]	Obrigatório para joyai; opcional para gptimage2	URLs de imagem. joyai aceita 1 a 3; gptimage2 entra em modo edição com imagens.
`size`	string	Opcional para joyai	Tamanho como 10241024. Padrão 10241024.
`quality`	string	Opcional para gptimage2	low, medium ou high. Padrão medium.
`resolution`	string	Opcional para gptimage2	1k, 2k ou 4k. Padrão 1k.
`aspect_ratio`	string	Opcional para gptimage2	1:1, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9 ou 21:9.
`output_format`	string	Opcional para gptimage2	png, jpeg ou webp. Padrão png.
`callback_url`	string	Opcional	URL armazenável com a tarefa para fluxos de callback.

Exemplo JoyAI Edit

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "joyai",
    "prompt": "Replace the mug logo with clean white text that says JOYAI while preserving reflections and shadows.",
    "images": ["https://example.com/source-product.jpg"],
    "size": "1024*1024"
  }'

Exemplo GPT Image 2

cURL

curl -X POST "https://joyai-image.com/api/v1/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gptimage2",
    "prompt": "A cinematic studio portrait of a red ceramic chair, softbox lighting, neutral backdrop",
    "quality": "high",
    "resolution": "2k",
    "aspect_ratio": "4:5",
    "output_format": "png"
  }'

Resposta

JSON

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "processing",
    "credits_charged": 88
  }
}

GET /api/v1/status

Consulte o status com o task ID de /api/v1/generate. O parâmetro model é opcional; task IDs são roteados automaticamente quando possível.

cURL

curl "https://joyai-image.com/api/v1/status?task_id=task_id_here" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "code": 200,
  "message": "success",
  "data": {
    "task_id": "task_id_here",
    "model": "gptimage2",
    "status": "succeeded",
    "credits_charged": 88,
    "images": ["https://cdn.example.com/result.png"],
    "error": null,
    "created_at": "2026-06-06 12:00:00"
  }
}

Erros

Erros usam o mesmo formato das respostas de sucesso. Respostas públicas não expõem nomes internos de provedores, workers ou roteamento.

JSON

{
  "code": 400,
  "message": "prompt is required",
  "data": null
}

Status	Significado
`400`	Parâmetros ausentes ou inválidos.
`401`	Chave API ausente ou inválida.
`402`	Créditos insuficientes.
`500`	Erro de serviço ou servidor. Contate o suporte se repetir.