01Instale com um comando
Escolha seu sistema. O instalador verifica o Node.js 18+, baixa o skill completo, pede o cliente e salva a chave localmente. Nenhuma imagem é gerada durante a instalação.
Abra o Terminal e cole o comando.
curl -fsSL https://www.modelkiwi.com/install/image-gen.sh | bashAbra o PowerShell (não o cmd) e cole o comando.
irm https://www.modelkiwi.com/install/image-gen.ps1 | iexAbra o Terminal e cole o comando.
curl -fsSL https://www.modelkiwi.com/install/image-gen.sh | bash- Escolha o cliente. Codex, Claude Code, OpenCode, OpenClaw, Hermes ou um diretório personalizado.
- Cole sua chave ModelKiwi. A entrada fica oculta. Crie a chave em Chaves de API no grupo default, com acesso ao modelo desejado.
- Reinicie ou recarregue o cliente. Peça: “Use $modelkiwi-image-gen para criar um pôster verde minimalista.”
modelkiwi-image-gen
O instalador confere os arquivos e mantém backup da versão anterior. Outros skills e as configurações de modelos do cliente são preservados.
Ambiente, local da chave e clientes
Se Node.js estiver ausente ou antigo, o script oferece instalar o LTS via nvm em macOS/Linux ou winget no Windows. É necessário aceitar a etapa; se preferir, instale pelo site oficial e execute novamente. O cliente de IA deve suportar skills locais e execução de scripts.
Chave salva em ~/.config/modelkiwi/.env(macOS/Linux,respeita XDG_CONFIG_HOME),%APPDATA%\modelkiwi\.env(Windows)。Os arquivos de chave e backups contêm segredos; não envie ao Git. A variável IMAGE_GEN_API_KEY tem prioridade sobre o arquivo.
Codex usa ~/.codex/skills; Claude Code usa ~/.claude/skills. O script também oferece outros clientes e diretório personalizado. Para um workspace OpenClaw personalizado, selecione seu diretório real.
Leia a instalação completa e a restauração de backups ↗02Escolha o modelo
Dois modelos, a mesma interface.
| Modelo | Quando escolher |
|---|---|
grok-imagine-image | Criação geral de imagens a partir de texto. |
grok-imagine-image-quality | Alternativa de qualidade; compare o resultado e o preço para o seu projeto. |
A disponibilidade e os preços vigentes estão no catálogo de modelos. Esta página não fixa preços nem garante disponibilidade do provedor.
03Ou peça à sua IA para instalar
Copie esta instrução para um assistente que consiga ler URLs, instalar skills e executar scripts locais. A chave fica na sua máquina.
Instale e habilite o skill ModelKiwi seguindo:
https://www.modelkiwi.com/install/skill/modelkiwi-image-gen/INSTALL.md
Instale a pasta completa para o cliente que estou usando, sem substituir outros skills.
Se não houver terminal interativo, use a opção --no-config e mantenha a chave existente.
Leia IMAGE_GEN_API_KEY ou o arquivo de configuração privado criado pelo instalador.
Não peça para eu publicar a chave no chat, nem a registre no código ou no Git.
Quando eu pedir uma imagem pela ModelKiwi, use os scripts do skill e salve o resultado localmente.Depois de instalar, basta descrever
Use $modelkiwi-image-gen para criar uma campanha de perfume minimalista, com luz da manhã e fundo verde-menta, sem texto.Para o modelo de qualidade, peça explicitamente grok-imagine-image-quality. A geração consome saldo conforme o catálogo. Se preferir integrar sua aplicação diretamente, consulte os exemplos de API abaixo.
04Faça uma chamada
O endpoint de criação de imagens é POST /v1/images/generations. Use a URL completa abaixo; SDKs que acrescentam o caminho automaticamente usam a base https://api.modelkiwi.com/v1.
curl https://api.modelkiwi.com/v1/images/generations \
-H "Authorization: Bearer $IMAGE_GEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-imagine-image",
"prompt": "A minimalist perfume campaign, morning light, soft mint backdrop, no text",
"n": 1,
"response_format": "b64_json"
}'O cURL retorna JSON com a imagem em Base64. Para salvar o arquivo automaticamente, use Python 3, sem dependências externas:
import base64
import json
import os
from pathlib import Path
from urllib.request import Request, urlopen
payload = {
"model": "grok-imagine-image",
"prompt": "A minimalist perfume campaign, morning light, soft mint backdrop, no text",
"n": 1,
"response_format": "b64_json",
}
request = Request(
"https://api.modelkiwi.com/v1/images/generations",
data=json.dumps(payload).encode("utf-8"),
headers={
"Authorization": "Bearer " + os.environ["IMAGE_GEN_API_KEY"],
"Content-Type": "application/json",
},
method="POST",
)
with urlopen(request, timeout=300) as response:
result = json.load(response)
image = base64.b64decode(result["data"][0]["b64_json"], validate=True)
if image.startswith(b"\x89PNG\r\n\x1a\n"):
extension = "png"
elif image.startswith(b"\xff\xd8\xff"):
extension = "jpg"
elif image[:4] == b"RIFF" and image[8:12] == b"WEBP":
extension = "webp"
else:
raise ValueError("Unexpected image format; inspect the response")
output = Path("generated-image." + extension)
output.write_bytes(image)
print(output.resolve())Salve como generate-image.py e execute python3 generate-image.py após definir a variável de ambiente. O arquivo é salvo na pasta atual. Uma execução faz uma chamada real e pode consumir saldo.
05Parâmetros
| Campo | Tipo | Uso neste guia |
|---|---|---|
model | string · obrigatório | Um dos dois modelos Grok listados acima. |
prompt | string · obrigatório | Descrição da imagem. |
n | integer | Use 1 para gerar uma imagem; outros limites dependem do provedor. |
response_format | string | b64_json ou url. O exemplo usa Base64. |
Não é uma chamada de chat: messages, temperature e streaming de texto não fazem parte deste exemplo.
06Leia a resposta
Na resposta JSON, procure data. Com b64_json, decodifique data[0].b64_json; com url, leia data[0].url e baixe a imagem enquanto o link estiver disponível. Não acrescente sua chave de API ao URL da imagem.
{
"data": [
{ "b64_json": "<BASE64_DA_IMAGEM>" }
]
}Os campos adicionais dependem do provedor. A extensão do arquivo deve corresponder ao conteúdo real — a resposta pode não ser PNG. Não espere que o cURL salve uma imagem diretamente: ele retorna JSON.
07Recursos disponíveis
Texto → imagem
Envio de modelo, prompt, quantidade e formato de retorno.
2K, referências e edição
O canal atual não encaminha integralmente os campos de tamanho, resolução ou imagem de referência. Não presuma que enviar esses campos ativa o recurso.
O catálogo pode exibir faixas 1K / 2K de cobrança. Isso, por si só, não comprova que a seleção de resolução está disponível neste canal. Este guia cobre a geração padrão por texto; edição e imagens de referência precisam de validação específica da integração.
08Resolva erros
| Sintoma | O que verificar |
|---|---|
| 401 / chave inválida | Chave ModelKiwi e cabeçalho Authorization: Bearer. |
| Sem canal disponível | Grupo default, nome exato do modelo, permissão do token e canal habilitado. |
| Saldo ou quota insuficiente | Saldo da conta, quota e validade do token. |
| 429 / limite de taxa | Reduza a concorrência; aguarde antes de tentar novamente. |
| 400 / parâmetro inválido | Use o payload mínimo deste guia e confira a mensagem do provedor. |
| Timeout / 5xx | Guarde o request ID para suporte. Confira os registros antes de repetir: a primeira chamada pode ter sido processada. |
Estrutura inspirada no guia do provedor