REFERÊNCIA

Imagem e vídeo pela API

Agosto 2026 · 6 min de leitura · Atualizado em 25/08/2026

Media usa a mesma chave e o mesmo gateway do texto, mas não o mesmo endereço. Esta página tem o contrato de cada endpoint, o que a resposta traz de verdade e os erros que você vai encontrar. Tudo conferido contra o gateway em 25/08/2026.

Antes de começar: sua chave tem mídia?

Media não vem em toda chave. A resposta está em uma linha, e é a mesma fonte que vale para qualquer dúvida de catálogo:

curl -s https://tokens.4clouders.com/v1/models \
  -H "Authorization: Bearer $ISOL_API_KEY"

Se aparecerem só isol-4.9, a sua chave é de texto. Com mídia liberada, a lista vem assim:

{
  "object": "list",
  "data": [
    { "id": "isol-4.9",        "object": "model" },
    { "id": "isol-image",      "object": "model" },
    { "id": "isol-image-text", "object": "model" },
    { "id": "isol-video",      "object": "model" }
  ]
}

Não escreva essa lista no seu código. Ela depende do plano da chave, e a chamada acima sempre diz a verdade do momento.

Imagem

Endpoint síncrono: você espera e recebe a imagem na mesma resposta.

curl -s https://tokens.4clouders.com/v1/images/generations \
  -H "Authorization: Bearer $ISOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "isol-image",
    "prompt": "um cubo azul sobre fundo branco, luz de estudio",
    "n": 1,
    "size": "1024x1024"
  }'

Gere em segundo plano. Noventa segundos é mais que o timeout padrão de muita biblioteca, e o corte vem do seu lado, não da API.

O ponto que mais derruba integração: a imagem volta em data[0].b64_json, em base64. O campo url existe na resposta, mas vem null. Quem copiou um exemplo da OpenAI e lê url direto recebe nulo e acha que a chamada falhou. Ela não falhou: o conteúdo está no outro campo.

Gravando o arquivo, em Python:

import base64, os
from openai import OpenAI

client = OpenAI(base_url="https://tokens.4clouders.com/v1",
                api_key=os.environ["ISOL_API_KEY"])

r = client.images.generate(
    model="isol-image",
    prompt="um cubo azul sobre fundo branco, luz de estudio",
    n=1, size="1024x1024",
)
open("saida.png", "wb").write(base64.b64decode(r.data[0].b64_json))

Quanto demora. Uma imagem de 512x512 levou cerca de 90 segundos na medição que fizemos. Não é um endpoint para deixar no caminho de um clique do usuário esperando na tela: gere em segundo plano e avise quando terminar. Se a sua aplicação tem timeout padrão de 30 ou 60 segundos, aumente antes de testar, senão você vai culpar a API por um corte que foi seu.

isol-image ou isol-image-text?

Os dois geram imagem no mesmo endpoint, mudando só o campo model. Use isol-image-text quando a peça precisa de texto legível dentro dela, como um cartaz ou um banner com chamada. Para foto de produto, cena e fundo, isol-image entrega melhor.

Uma coisa que vale dizer antes que você descubra tentando: difusão não desenha logo de marca de forma confiável a partir do zero. Se a peça precisa do seu logo exato, gere o fundo e componha o logo por cima, ou parta de uma imagem real. É limitação da tecnologia, não da nossa instalação dela.

Vídeo

Vídeo é assíncrono, e tem que ser: leva minutos. Você envia o pedido, recebe um job e consulta até ficar pronto.

curl -s https://tokens.4clouders.com/v1/videos \
  -H "Authorization: Bearer $ISOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "isol-video", "prompt": "um cubo azul girando devagar"}'

A resposta vem com HTTP 202 e o job:

{
  "id": "vid_f1621757c272",
  "object": "video.job",
  "status": "queued",
  "queue_position": 0,
  "eta_seconds": 180
}

A partir daí, consulte pelo id:

curl -s https://tokens.4clouders.com/v1/videos/vid_f1621757c272 \
  -H "Authorization: Bearer $ISOL_API_KEY"

Consultar a cada segundo não deixa o vídeo pronto mais cedo, só gasta a sua cota. O campo eta_seconds existe justamente para você espaçar.

O job traz status, progress, queue_position, eta_seconds, e dois campos que ficam null até o fim: url, com o vídeo pronto, e error, se algo falhar. Trate os dois: um job que termina em erro também sai da fila.

Consulte com intervalo, não em laço apertado. O eta_seconds existe para isso. Perguntar a cada segundo não deixa o vídeo pronto mais cedo, só gasta a sua cota de requisição. Consultar a cada 15 ou 20 segundos é suficiente.

Os erros que você vai encontrar

ATENÇÃO

Quatro erros respondem por quase tudo

Vale ler esta tabela antes de subir. Os quatro abaixo aparecem em quase todo primeiro uso, e três deles têm a mesma causa.

Ir para produção

Código	O que aconteceu	O que fazer
`404` no endpoint	Endereço errado. `/v1/images` não existe.	Use `/v1/images/generations`.
`404` com Model Group	Modelo de imagem chamado no endpoint de chat, ou o contrário.	Cada modelo tem o seu endereço. Veja a tabela em Primeiros passos.
`400` Invalid model name	Faltou o campo `model` no corpo.	Media não tem modelo padrão: é sempre explícito.
`429` limite de jobs simultâneos	A chave já tem mídia em processamento.	Enfileire do seu lado e espere o job anterior. Não é falta de crédito.

Levando para produção

Uma fila do seu lado. O limite de jobs simultâneos por chave existe. Se o seu produto pode disparar dez pedidos ao mesmo tempo, segure na sua aplicação, senão o décimo volta com 429 na cara do seu usuário.
Guarde o arquivo, não o base64. Grave a imagem no seu storage assim que chegar e trabalhe com a sua URL. Base64 em banco de dados incha a linha e o backup.
Trate o job que falha. Rede cai, prompt é recusado, acontece. O campo error existe para isso e o seu código precisa ler.
Timeout generoso na imagem. Cerca de 90 segundos foi o que medimos; deixe folga e gere fora do caminho do clique.
A conta é a mesma. Media consome do mesmo pacote da chave, e aparece no mesmo extrato de /key/info. Uma chave por aplicação continua valendo, e aqui vale ainda mais: geração de mídia é o que mais pesa.

Vai colocar mídia em produção e quer revisar o desenho antes? Fale com a engenharia. Preferimos ajustar o fluxo com você antes de você descobrir o limite em produção.