Modelos de imagem
Gere e edite imagens usando a interface de modelos de imagem da OneMux.
Sobre a interface
Os modelos de imagem usam uma interface Images independente. Não envie solicitações de geração de imagens para /v1/chat/completions.
- Geração de imagens:
POST https://api.onemux.net/v1/images/generations - Edição de imagens:
POST https://api.onemux.net/v1/images/edits - Autenticação:
Authorization: Bearer YOUR_API_KEY - Modelos: use o ID real do modelo de imagem retornado pela interface da lista de modelos atual
Primeiro, obtenha os modelos disponíveis no momento:
curl https://api.onemux.net/v1/models \
-H "Authorization: Bearer $ONEMUX_API_KEY"
O suporte do modelo de imagem a geração, edição, imagens de referência, dimensões, qualidade, formato de saída e outros parâmetros depende da lista de modelos e dos recursos reais do provedor upstream.
Geração de imagens
Use /v1/images/generations para enviar uma solicitação de geração de imagem a partir de texto.
curl https://api.onemux.net/v1/images/generations \
-H "Authorization: Bearer $ONEMUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_IMAGE_MODEL_ID",
"prompt": "一只坐在窗边的橘猫,午后自然光,写实摄影风格",
"size": "1024x1024",
"quality": "medium"
}'
Parâmetros comuns:
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
model | Sim | ID de um modelo de imagem disponível no momento |
prompt | Sim | Descrição do conteúdo da imagem |
size | Não | Dimensões da imagem; o intervalo permitido depende do modelo |
quality | Não | Qualidade da imagem; os valores aceitos dependem do modelo |
n | Não | Número de imagens geradas; o intervalo permitido depende do modelo |
response_format | Não | b64_json ou url; disponível apenas para modelos compatíveis |
background | Não | Fundo transparente ou opaco; disponível apenas para modelos compatíveis |
output_format | Não | png, jpeg, webp; disponível apenas para modelos compatíveis |
Não use em outros modelos de imagem parâmetros compatíveis com apenas um modelo específico. Se ocorrer model_not_found, invalid_model ou um erro de parâmetro não compatível, primeiro confirme o ID e os recursos do modelo.
Edição de imagens
Use /v1/images/edits para editar imagens existentes. Modelos de imagem comuns compatíveis com OpenAI usam multipart/form-data para enviar imagens:
curl https://api.onemux.net/v1/images/edits \
-H "Authorization: Bearer $ONEMUX_API_KEY" \
-F "model=YOUR_IMAGE_MODEL_ID" \
-F "image[]=@input.png" \
-F "prompt=将背景改为浅蓝色,保持主体和文字不变" \
-F "size=1024x1024"
É possível enviar várias imagens de referência repetindo image[], por exemplo:
-F "image[]=@person.png" \
-F "image[]=@product.png"
A quantidade e o formato das imagens, máscaras, URLs de imagens de referência e o formato JSON de edição dependem do modelo e do canal upstream. Use esses parâmetros somente quando houver suporte explícito do modelo.
Uso com Python
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["ONEMUX_API_KEY"],
base_url="https://api.onemux.net/v1",
)
result = client.images.generate(
model="YOUR_IMAGE_MODEL_ID",
prompt="一张简洁的蓝色科技风产品海报",
size="1024x1024",
)
print(result.data[0].b64_json or result.data[0].url)
A edição de imagens normalmente exige o envio direto de arquivos multipart. Se a versão atual do SDK Python não for compatível com os parâmetros de edição do modelo desejado, use a solicitação cURL acima.
Resposta
Uma resposta bem-sucedida normalmente contém o array data:
{
"created": 1760000000,
"data": [
{
"b64_json": "iVBORw0KGgo..."
}
]
}
Alguns modelos retornam um endereço de imagem quando a solicitação define response_format como url:
{
"created": 1760000000,
"data": [
{
"url": "https://example.com/generated-image.png"
}
]
}
Quando receber Base64, salve o arquivo usando o formato real da imagem. Quando receber uma URL, baixe e salve a imagem imediatamente para evitar que o endereço temporário expire.
Cobrança
Os modelos de imagem não usam um único esquema de cobrança por Token. A OneMux cobra de acordo com as regras de preço publicadas para o modelo no momento, que podem incluir:
- Cobrança por quantidade de imagens geradas
- Cobrança por resolução da imagem ou nível de qualidade
- Cobrança por Tokens de entrada e saída de imagem ou por outros usos do provedor upstream
Consulte as informações atuais do modelo correspondente no Catálogo de modelos para saber os preços, as unidades de cobrança e as especificações compatíveis. Em geral, uma solicitação com falha não gera a cobrança pelas imagens correspondentes a um resultado bem-sucedido, mas o comportamento específico depende do que é exibido na página e da resposta do servidor.
Perguntas frequentes
Por que não posso usar a interface de conversa para gerar imagens?
Os modelos de imagem usam uma rota Images independente. O envio para /v1/chat/completions ou para outra interface incompatível pode resultar em um erro indicando que o modelo não oferece suporte ao endpoint ou que há um problema com os parâmetros.
Por que consigo consultar o nome do modelo, mas a solicitação ainda falha?
Verifique se o modelo permite geração ou edição de imagens, se a chave de API atual tem permissão, se os parâmetros da solicitação estão dentro do intervalo compatível com o modelo e se o canal upstream correspondente está disponível.
Por que a resposta contém Base64 em vez de um link para a imagem?
O formato da resposta depende do modelo ou da configuração response_format. Se receber b64_json, decodifique e salve os dados no cliente. Se receber url, baixe a imagem do endereço retornado.
O que fazer quando a geração de imagens está lenta?
Solicitações de alta resolução, alta qualidade ou edição complexa podem levar mais tempo. Defina um tempo limite razoável para as solicitações do cliente. Não envie novamente a mesma solicitação só porque o cliente atingiu o tempo limite, para evitar tarefas ou cobranças duplicadas.
GPT Image 2.6: SVG, GIF e complexidade
A série GPT Image 2.6 adiciona suporte a saída SVG, animações GIF e ao parâmetro complexity. Esses recursos só estão disponíveis em modelos e canais upstream compatíveis.
Saída SVG
SVG é usado para geração de imagens, não para edição. Ao chamar a interface de geração, defina output_format como svg e n como 1. Os dados da imagem na resposta estão em Base64; decodifique-os e salve-os como um arquivo .svg.
{
"model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
"prompt": "一个简洁的蓝色几何图形标志",
"output_format": "svg",
"n": 1
}
Algumas configurações upstream também podem exigir um objeto svg adicional, como svg.model. Adicione-o somente quando as instruções do modelo ou do canal exigirem isso explicitamente. Nem todos os modelos e canais de imagem oferecem suporte a SVG.
Saída de animações GIF
Modelos GPT Image 2.6 compatíveis com esse recurso podem definir output_format como gif na interface de geração de imagens. Se houver suporte no modelo, use frame_count e frame_duration_ms para definir o número de quadros da animação e a duração de cada quadro. GIF é um recurso de geração; não presuma que a interface de edição de imagens também possa retornar GIFs.
{
"model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
"prompt": "一只蓝色小鸟循环拍打翅膀的动画",
"output_format": "gif",
"frame_count": 6,
"frame_duration_ms": 200
}
Parâmetro de complexidade
A série GPT Image 2.6 oferece suporte a complexity: low, medium, high. Para edições simples, experimente uma complexidade menor. Para imagens com muito texto ou layouts complexos, experimente uma complexidade maior. Esse parâmetro é diferente de quality; uma complexidade maior pode tornar a geração mais lenta.
{
"model": "YOUR_GPT_IMAGE_2_6_MODEL_ID",
"prompt": "一张细节丰富的城市街景编辑插画",
"complexity": "high",
"quality": "high"
}
Os parâmetros acima não são compatíveis com todos os modelos. Se a interface indicar que um parâmetro não é compatível, remova os parâmetros opcionais ou confirme os recursos do modelo e do canal selecionados.