Por recurso
Imagens
Escolha um modelo, copie a requisição e receba a imagem. Tudo abaixo acompanha o modelo que você escolher.
#1. Escolha um modelo
gemini-2.5-flash-image-preview$0.0125 / requisiçãoTarefa assíncronaLimites e status
12 modelos online para isto. Trocar de modelo altera o código abaixo.
#2. Copie a requisição
Substitua YOUR_API_KEY pela sua chave e execute. As opções mostradas são as que este modelo aceita.
https://www.aisplice.store/v1/images/tasksBearer API keyTarefa assíncronaOpçõesSó aparecem as opções publicadas para este modelo.
# Requires curl and jq
API_KEY="${API_KEY:-YOUR_API_KEY}"
# 1. Submit once
SUBMITTED=$(curl --fail-with-body -sS https://www.aisplice.store/v1/images/tasks \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: model-docs-$(date +%s)-$$" \\
-d '{
"model": "Nano Banana",
"prompt": "A cinematic scene with careful composition",
"size": "auto",
"resolution": "1K",
"n": 1
}')
TASK_ID=$(printf '%s' "$SUBMITTED" | jq -r '.task_id // .id // empty')
if [ -z "$TASK_ID" ]; then
printf '%s\n' "$SUBMITTED" >&2
exit 1
fi
echo "task_id=$TASK_ID"
# 2. Poll until terminal
while true; do
STATUS_JSON=$(curl --fail-with-body -sS \
"https://www.aisplice.store/v1/images/tasks/$TASK_ID" \
-H "Authorization: Bearer $API_KEY")
STATUS=$(printf '%s' "$STATUS_JSON" | jq -r '.status // empty' | tr '[:upper:]' '[:lower:]')
echo "status=$STATUS"
case "$STATUS" in
completed|succeeded|success) break ;;
failed|failure|cancelled|canceled)
printf '%s\n' "$STATUS_JSON" | jq .
exit 1
;;
esac
sleep 3
done
# 3. Fetch the final result
curl --fail-with-body -sS \
"https://www.aisplice.store/v1/images/tasks/$TASK_ID/content" \
-H "Authorization: Bearer $API_KEY" | jq .URLs de mídia públicas são recomendadas em produção. Envie primeiro o arquivo local e depois coloque public_url na requisição do modelo. Evite corpos grandes em Base64.
Ler o guia de uploadTodos os parâmetros
Todos os campos que este modelo aceita, com os valores permitidos.
Todos os parâmetros
Todos os campos que este modelo aceita, com os valores permitidos.
modelIdentificador exato do modelo para esta requisição.
gemini-2.5-flash-image-previewpromptInstrução que descreve o resultado desejado.
sizeProporção ou dimensões da saída.
auto1:12:33:23:44:34:55:49:1616:921:9resolutionResolução da saída solicitada.
1KnimagesOptional reference images, up to 14.
Ciclo de vida da resposta
Status da tarefa, estados finais e exemplos de resposta com o resultado.
Ciclo de vida da resposta
Status da tarefa, estados finais e exemplos de resposta com o resultado.
{
"id": "task_xxx",
"task_id": "task_xxx",
"object": "image.task",
"model": "Nano Banana",
"status": "queued"
}{
"created": 1720000000,
"data": [
{
"url": "https://media.example/result.png"
}
]
}Aguardando
queued · submitted · in_progress · processing
Sucesso
completed · succeeded · success
Falha
failed · failure · cancelled · canceled
#3. Obtenha o resultado
A chamada de envio responde na hora com um task_id. Consulte a tarefa a cada poucos segundos até o status ser completed, ou passe webhook_url e nós chamamos você quando terminar.
GET https://www.aisplice.store/v1/images/tasks/{task_id}
GET https://www.aisplice.store/v1/images/tasks/{task_id}/content
Cobrado só em caso de sucesso
Valores de status e consultas →Receba um callback em vez de consultar →
#Quando algo dá errado
- 400 com o nome de um campo: essa opção não é aceita por este modelo; use os valores listados na etapa 2.
- Conteúdo recusado pelo modelo: reformule o prompt; requisições recusadas não são cobradas.
- 402: o saldo não cobre esta requisição; recarregue em Carteira e tente novamente.
- 429: diminua o ritmo e tente novamente após os segundos de Retry-After.
- 503 model_not_found: o nome do modelo está errado ou o modelo está offline; escolha um na etapa 1.
#Imagens de referência
Passe URLs públicas de imagens no campo de imagem de referência indicado na etapa 2. Para um arquivo local, faça o upload primeiro e use a URL retornada.
Integrando ao seu produtoQuais opções mostrar primeiro aos seus usuários e quais deixar para depois.
Quais opções mostrar primeiro aos seus usuáriosComece com o prompt e um controle de preço; adicione o resto quando o fluxo básico funcionar.+
Intenção criativa
Campos como prompt pertencem à UI porque o usuário entende diretamente o resultado que eles mudam.
Multiplicador de custo
Campos como duração, resolução, tamanho e quantidade só devem ser introduzidos quando o preço já puder ser explicado.
Troca de modo
Campos como image, mask ou IDs de continuação mudam o próprio fluxo e só devem aparecer em modos dedicados.
Infraestrutura do sistema
Campos como webhook_secret são para integradores, não para criadores no dia a dia, então mantenha-os fora da UI padrão.
prompt- Quando expor
- Sempre. É a principal entrada criativa das tarefas de imagem.
- Padrão recomendado
- Obrigatório na UI.
- Por que importa
- Controla diretamente o resultado; escondê-lo torna o recurso inutilizável.
size- Quando expor
- Exponha já na primeira versão se a cobrança variar conforme as dimensões da saída.
- Padrão recomendado
- Comece com uma proporção recomendada, como 1:1.
- Por que importa
- Afeta tanto o custo quanto a composição da saída, então os usuários precisam de uma escolha de tamanho simples desde cedo.
quality- Quando expor
- Exponha só depois que os usuários pedirem claramente um nível mais alto ou mais barato.
- Padrão recomendado
- Mantenha no servidor, com o padrão do modelo.
- Por que importa
- Muda preço e latência, mas geralmente não precisa ser um controle desde o primeiro dia.
n- Quando expor
- Exponha só quando a geração em lote for um fluxo central.
- Padrão recomendado
- Padrão: 1.
- Por que importa
- Multiplica o custo imediatamente e pode deixar a primeira experiência confusa.
mask / image- Quando expor
- Exponha só em produtos de edição ou de imagem de referência.
- Padrão recomendado
- Oculte no modo texto para imagem.
- Por que importa
- Esses campos transformam o produto de geração em edição, então não devem vazar para o fluxo básico.
Phase 1
- prompt
- one size or one duration default
- submit -> poll -> content
Phase 2
- one quality or resolution selector
- clear pricing hint
Phase 3
- advanced controls such as reference media, continuation, webhook, or vendor-specific tuningMantenha uma única fonte da verdade para os resultados
Ainda com problemas?
Envie para nós o ID da requisição ou a mensagem de erro e vamos investigar.