curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: <unique-operation-key>' \
--data '{
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/images/generations",
headers={
"Authorization": "Bearer <token>",
"Accept": "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
json={
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
}
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
body: JSON.stringify({
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
})
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
Muse Image Ext
Geração de imagens Muse Image Ext
Gere uma imagem WebP por solicitação a partir de texto ou de até 9 imagens de referência.
POST
/
v1
/
images
/
generations
curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: <unique-operation-key>' \
--data '{
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/images/generations",
headers={
"Authorization": "Bearer <token>",
"Accept": "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
json={
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
}
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
body: JSON.stringify({
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
})
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
Esta API é assíncrona. Salve o ID da tarefa após o envio e consulte
GET /v1/tasks/{task_id} para obter status e resultados. Na resposta padrão de envio, o ID está em data[0].task_id.curl --request POST \
--url https://api.apimart.ai/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Idempotency-Key: <unique-operation-key>' \
--data '{
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
}'
import requests
response = requests.post(
"https://api.apimart.ai/v1/images/generations",
headers={
"Authorization": "Bearer <token>",
"Accept": "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
json={
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
}
)
response.raise_for_status()
print(response.json())
const response = await fetch("https://api.apimart.ai/v1/images/generations", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": "<unique-operation-key>"
},
body: JSON.stringify({
"model": "muse-image-ext",
"prompt": "A red ceramic cup on a white table, soft studio lighting, product photography, no text",
"aspect_ratio": "1:1",
"n": 1
})
});
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());
{
"code": 200,
"data": [
{
"status": "submitted",
"task_id": "task_01K..."
}
]
}
Cabeçalhos da solicitação
string
obrigatório
Use uma APIMart API Key no formato
Bearer <token>. O envio e as consultas exigem autenticação com a mesma identidade de usuário.string
Fortemente recomendado. Use uma nova chave para cada geração independente (1–191 caracteres ASCII visíveis; UUID recomendado). Substitua
<unique-operation-key> nos exemplos. Após um timeout de envio ou falha de rede, repita com o mesmo endpoint, corpo, versão de resposta e chave. Depois de receber o ID, consulte apenas essa tarefa.Parâmetros da solicitação
string
obrigatório
Valor fixo:
muse-image-ext.string
obrigatório
Descrição do conteúdo desejado, em chinês ou inglês. Não pode ficar vazia após remover espaços nas extremidades. Obrigatória mesmo com imagens de referência.
string[]
Até 9 entradas de imagens de referência não vazias. Aceita URLs públicas, Data URIs (como
data:image/png;base64,...) ou base64 puro. Omita ou envie [] para gerar apenas a partir de texto. PNG, JPEG e WebP são recomendados. As URLs devem ser acessíveis diretamente pelo servidor, sem cookies de login do navegador.O tamanho original combinado de todas as imagens não pode exceder 11 MiB (11.534.336 bytes). É um limite total, não por imagem. A codificação base64 aumenta o corpo da solicitação. Não envie URLs blob:, caminhos locais ou objetos File.string
Aceita as sete proporções abaixo. Quando omitido, texto para imagem usa
1:1; com referências, segue a composição delas. Uma proporção explícita tem prioridade. Para seleção automática, omita o campo; não envie "auto".1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3string
Campo de compatibilidade que aceita as sete proporções acima ou
auto, mas não dimensões em pixels como 1024x1024. Enviar apenas size: "auto" equivale a não definir uma proporção. Prefira aspect_ratio. Se ambos forem válidos, aspect_ratio tem prioridade, mas os campos são validados separadamente: uma proporção válida não corrige um size inválido.integer
padrão:"1"
Um único resultado por solicitação. Só aceita o número
1. Valores explícitos como 0, negativos ou maiores que 1 causam erro.Retorna uma URL WebP. O modelo determina as dimensões; não é possível escolher tamanhos em pixels nem níveis 1K / 2K / 4K. Não envie
resolution não vazio nem campos de duração.Outros parâmetros opcionais
string
URL base do backend para notificações da tarefa. A plataforma remove as barras finais e acrescenta
/callback: https://your-backend.example/muse torna-se https://your-backend.example/muse/callback. Omita se usar apenas consultas periódicas.string
Controla o idioma dos erros do Webhook, não o conteúdo gerado. Valores:
zh, en, ja, ko, ru, fr, de, id, pt, es. Tags regionais como zh-CN não são aceitas. Nas consultas, envie o idioma separadamente como parâmetro GET.Geração com imagens de referência
{
"model": "muse-image-ext",
"prompt": "Keep the cup from the reference image and place it on a wooden cafe table in warm natural light",
"image_urls": [
"https://your-cdn.example/cup.png"
],
"n": 1
}
aspect_ratio para uma proporção fixa. Adicione outras referências em image_urls, até 9 no total.
Resposta de envio
A resposta padrão é HTTP200, com data como array. submitted significa que a tarefa foi aceita, não concluída. Salve data[0].task_id e depois consulte a tarefa.
Versão de resposta opcional: 2026-07-27
Versão de resposta opcional: 2026-07-27
Com o cabeçalho Esta versão não altera a estrutura da resposta GET. Ao adicionar esse cabeçalho, não continue lendo o ID da resposta de envio em
X-APIMart-Response-Version: 2026-07-27, o envio retorna HTTP 202. Leia o ID em data.id e o caminho de consulta em data.poll_url.{
"code": 202,
"request_id": "req_example",
"data": {
"id": "task_01K...",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01K..."
}
}
data[0].task_id.Consultar status e resultados
Use o ID completo recebido no envio e a mesma identidade de usuário.language é opcional e define o idioma dos erros. Consulte todos os campos em Status da tarefa.
curl --request GET \
--url 'https://api.apimart.ai/v1/tasks/<task_id>?language=pt' \
--header 'Authorization: Bearer <token>'
data.status | Ação |
|---|---|
pending / processing | Na fila ou em processamento; continue consultando. |
completed | Geração concluída com sucesso; pare as consultas e leia a URL do resultado. |
failed | Falha na geração; pare as consultas e leia data.error.message. |
unknown / … | Status incerto. Guarde o ID e limite as novas consultas; não trate como sucesso nem gere novamente de forma automática. |
data.status. HTTP 200 ou progress: 100 não indica, por si só, sucesso na geração. Um polling_error durante o processamento não é uma falha terminal.
Exemplo de resposta de consulta concluída (URL do resultado ilustrativa):
{
"code": 200,
"data": {
"id": "task_01K...",
"status": "completed",
"progress": 100,
"result": {
"images": [
{
"url": [
"https://cdn.example/generated-image.webp"
]
}
]
}
}
}
data é um objeto e url é um array de strings. O primeiro resultado está em data.result.images[0].url[0]. Se presente, expires_at é o vencimento em segundos Unix; salve os arquivos necessários antes disso. actual_time mede o tempo de processamento da tarefa, não a duração de reprodução do vídeo.
Limitações e tratamento de erros
Vídeos e áudios de referência, máscaras, controle do primeiro/último quadro, extensão e remix não são compatíveis.quality não tem efeito. Omita seed, negative_prompt, width, height, response_format e output_format, pois não são parâmetros de geração deste modelo. async: false não ativa geração síncrona e stream não oferece um fluxo SSE de geração.
HTTP / error.code | Ação |
|---|---|
400 / invalid_request_error | Verifique o prompt, a quantidade de referências, a proporção, a quantidade de resultados e as especificações fixas. |
409 / idempotency_in_progress | Aguarde conforme Retry-After e repita a solicitação original com a mesma chave de idempotência. |
409 / idempotency_key_reused | A mesma chave foi usada em solicitações diferentes. Corrija o uso das chaves; cada geração independente exige uma nova chave. |
409 / idempotency_result_indeterminate | Pare os reenvios automáticos e preserve a chave e os dados da tarefa para investigação. |
429 | Aguarde conforme Retry-After antes de tentar novamente. |
200; examine data.status e data.error.message. Um erro de rede ou 5xx durante o envio pode ocorrer após a aceitação, portanto não reenvie imediatamente com uma nova chave.