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: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
--header 'X-APIMart-Response-Version: 2026-07-27' \
--data '{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}'
import requests
import uuid
url = "https://api.apimart.ai/v1/images/generations"
payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-APIMart-Response-Version": "2026-07-27",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())
const url = "https://api.apimart.ai/v1/images/generations";
const payload = {
model: "grok-imagine-2.0-ext",
prompt: "A red apple on a white ceramic plate, clean studio product photo",
n: 1,
size: "1:1",
resolution: "quality",
response_format: "url",
};
const headers = {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-APIMart-Response-Version": "2026-07-27",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then(async (response) => {
console.log(response.status, await response.json());
})
.catch((error) => console.error("Error:", error));
{
"code": 202,
"request_id": "2026081111342261665927mpb4IPDb",
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
}
}
{
"request_id": "20260811...",
"error": {
"message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
"type": "invalid_response_format",
"param": "",
"code": "invalid_response_format"
}
}
{
"error": {
"code": 401,
"message": "Authentication failed. Please check your API key",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "Insufficient balance. Please top up and try again",
"type": "payment_required"
}
}
{
"error": {
"code": 429,
"message": "Too many requests. Please try again later",
"type": "rate_limit_error"
}
}
Grok Imagine 2.0 Ext
Grok Imagine 2.0 Ext generación de imágenes
- Texto a imagen asíncrono; consulte con task_id
- 1–12 imágenes por solicitud; cobro por imagen entregada con éxito ($0.08 cada una)
- Salida solo en URL; sin imagen a imagen / streaming
- Las URL de imagen expiran en 72 horas
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: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
--header 'X-APIMart-Response-Version: 2026-07-27' \
--data '{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}'
import requests
import uuid
url = "https://api.apimart.ai/v1/images/generations"
payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-APIMart-Response-Version": "2026-07-27",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())
const url = "https://api.apimart.ai/v1/images/generations";
const payload = {
model: "grok-imagine-2.0-ext",
prompt: "A red apple on a white ceramic plate, clean studio product photo",
n: 1,
size: "1:1",
resolution: "quality",
response_format: "url",
};
const headers = {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-APIMart-Response-Version": "2026-07-27",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then(async (response) => {
console.log(response.status, await response.json());
})
.catch((error) => console.error("Error:", error));
{
"code": 202,
"request_id": "2026081111342261665927mpb4IPDb",
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
}
}
{
"request_id": "20260811...",
"error": {
"message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
"type": "invalid_response_format",
"param": "",
"code": "invalid_response_format"
}
}
{
"error": {
"code": 401,
"message": "Authentication failed. Please check your API key",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "Insufficient balance. Please top up and try again",
"type": "payment_required"
}
}
{
"error": {
"code": 429,
"message": "Too many requests. Please try again later",
"type": "rate_limit_error"
}
}
Texto a imagen · tareas asíncronas. Envíe
El nombre del modelo es fijo:
POST /v1/images/generations y, a continuación, consulte Obtener estado de la tarea.El nombre del modelo es fijo:
grok-imagine-2.0-ext. No admitido: imágenes de referencia, stream ni valores de response_format distintos de url.Para trabajar con capas de objetos o editar regiones seleccionadas, consulta Capas y edición de regiones.
No ponga claves de API en bundles del navegador (
VITE_* / NEXT_PUBLIC_*, LocalStorage, etc.). Prefiera llamar a su propio BFF desde el navegador; mantenga la clave de APIMart en el servidor.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: 8eacb46d-ef4e-4f4e-82de-830bd8bc67e2' \
--header 'X-APIMart-Response-Version: 2026-07-27' \
--data '{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}'
import requests
import uuid
url = "https://api.apimart.ai/v1/images/generations"
payload = {
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url",
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
"Accept": "application/json",
"Idempotency-Key": str(uuid.uuid4()),
"X-APIMart-Response-Version": "2026-07-27",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code, response.json())
const url = "https://api.apimart.ai/v1/images/generations";
const payload = {
model: "grok-imagine-2.0-ext",
prompt: "A red apple on a white ceramic plate, clean studio product photo",
n: 1,
size: "1:1",
resolution: "quality",
response_format: "url",
};
const headers = {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
Accept: "application/json",
"Idempotency-Key": crypto.randomUUID(),
"X-APIMart-Response-Version": "2026-07-27",
};
fetch(url, {
method: "POST",
headers: headers,
body: JSON.stringify(payload),
})
.then(async (response) => {
console.log(response.status, await response.json());
})
.catch((error) => console.error("Error:", error));
{
"code": 202,
"request_id": "2026081111342261665927mpb4IPDb",
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"object": "generation.task",
"type": "image",
"status": "pending",
"progress": 0,
"poll_url": "/v1/tasks/task_01KZQE5CM0Y3KZ6M1N1BK619MX"
}
}
{
"request_id": "20260811...",
"error": {
"message": "`response_format` for grok-imagine-2.0-ext only supports `url` (got: b64_json)",
"type": "invalid_response_format",
"param": "",
"code": "invalid_response_format"
}
}
{
"error": {
"code": 401,
"message": "Authentication failed. Please check your API key",
"type": "authentication_error"
}
}
{
"error": {
"code": 402,
"message": "Insufficient balance. Please top up and try again",
"type": "payment_required"
}
}
{
"error": {
"code": 429,
"message": "Too many requests. Please try again later",
"type": "rate_limit_error"
}
}
Capacidades y límites
| Dimensión | Contrato |
|---|---|
| Modelo | Fijo grok-imagine-2.0-ext |
| Capacidad | Solo texto a imagen |
| Modo | Tarea asíncrona |
Cantidad n | 1–12, valor predeterminado 1 |
size | 7 relaciones de aspecto + 5 alias de píxeles (abajo) |
| Salida | Solo response_format=url (también el valor predeterminado) |
| Calidad | Campo público resolution; valor verificado quality |
| No admitido | Imagen a imagen, stream=true, quality público, style, b64_json / base64 |
| Facturación | Precio unitario fijo; se cobra por imágenes entregadas con éxito |
Autenticación y headers recomendados
string
requerido
Token Bearer. Obtenga una clave en la página de API Key.
Authorization: Bearer YOUR_API_KEY
| Header | Notas |
|---|---|
Content-Type | application/json (envío) |
Accept | application/json |
Idempotency-Key | Muy recomendado. Nuevo UUID por generación confirmada por el usuario; los reintentos de red deben reutilizar la misma key y el mismo body |
X-APIMart-Response-Version | Prefiera 2026-07-27 para una forma de envío estable (data.id) |
Parámetros de la solicitud
string
requerido
Valor fijo:
grok-imagine-2.0-extboolean
predeterminado:"false"
Indica si se debe moderar el contenido antes de enviar la tarea de imagen.
true: revisar los prompts y las imágenes de entrada conomni-moderation-latestfalseu omitido: no enviar una solicitud de moderación, sin coste ni latencia de moderación adicionales (predeterminado)
string
requerido
Prompt. Debe ser no vacío tras el trim. Haga trim antes de enviar.
integer
predeterminado:"1"
Cantidad de imágenes:
1–12. Un 0 explícito produce error. Omítalo para 1.string
Relación de aspecto. Prefiera cadenas de proporción (la UI solo debe mostrar proporciones):
Alias de píxeles:
size | Orientación | Uso típico |
|---|---|---|
1:1 | Cuadrado | Producto, avatar |
2:3 | Vertical | Póster, cuerpo entero |
3:2 | Horizontal | Foto, escena amplia |
3:4 | Vertical | Comercio electrónico, personas |
4:3 | Horizontal | Arte de visualización |
9:16 | Vertical | Portada de Story / video corto |
16:9 | Ancho | Banner, portada de video |
1024x1024 (1:1), 1024x1792 (2:3), 1792x1024 (3:2), 720x1280 (9:16), 1280x720 (16:9).Los valores fuera de la lista blanca devuelven 400 invalid_size (p. ej. 1:2, 2:1, 4:5, auto).Los píxeles reales de una proporción pueden diferir de la tabla de alias (p. ej.
1:1 puede devolver 1408×1408). Confíe en la imagen devuelta; no reescriba size a partir de los píxeles medidos.string
Campo de modo de calidad. Valor verificado:
quality.- Omítalo (el modelo es modo calidad por defecto), o
- Pase
resolution: "quality"de forma explícita
1K / 2K / 4K; el encuadre lo controla size.No envíe el campo público
quality — recibirá 400 invalid_quality. Use resolution.string
predeterminado:"url"
Solo se permite
url. Puede omitirse. b64_json / base64 → 400 invalid_response_format.string
URL base HTTPS pública opcional. En estado terminal, la plataforma hace POST a
{webhook}/callback. Solo en el servidor — vea Webhook.Parámetros no admitidos
| Parámetro | Comportamiento |
|---|---|
quality | 400 invalid_quality → use resolution |
style | 400 invalid_style |
image_urls / image_with_roles | 400 invalid_image_input |
stream: true | 400 invalid_stream |
response_format: "b64_json" / "base64" | 400 invalid_response_format |
Ejemplos de solicitud
Mínimo
{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo"
}
Recomendado
{
"model": "grok-imagine-2.0-ext",
"prompt": "A red apple on a white ceramic plate, clean studio product photo",
"n": 1,
"size": "1:1",
"resolution": "quality",
"response_format": "url"
}
Respuesta de envío
PrefieraX-APIMart-Response-Version: 2026-07-27. El éxito es HTTP 202; el id de la tarea es data.id (no dependa del legado data[0].task_id).
Conserve:
data.idpara el sondeo (polling)request_idpara depuración en el gateway- el
Idempotency-Keypara reintentos seguros cuando el resultado sea desconocido - los parámetros originales de la solicitud para UI / soporte
Idempotencia y reintentos seguros
La generación de imágenes es facturable — se recomienda encarecidamenteIdempotency-Key (1–191 caracteres ASCII imprimibles; UUID es lo más sencillo; se retiene ~24 horas).
| Escenario | Comportamiento | Acción |
|---|---|---|
| Misma key + mismo body ya completado | Replay; header Idempotency-Replayed: true | Use el mismo id de tarea |
| Misma key aún en curso | 409 idempotency_in_progress + Retry-After | Espere y reintente con la misma key y el mismo body |
| Misma key, body distinto | 409 idempotency_key_reused | Una nueva tarea lógica necesita una key nueva |
| Resultado indeterminado | 409 idempotency_result_indeterminate | No cree una key nueva; investigue con la antigua |
Consultar tareas
GET /v1/tasks/{task_id}?language=en
Authorization: Bearer YOUR_API_KEY
Accept: application/json
language opcional: zh / en / ko / ja (solo localización de mensajes de error). Vea Obtener estado de la tarea.
Estados
status | Terminal | Tratamiento |
|---|---|---|
pending / processing | No | Siga consultando (result puede estar ausente — no es un fallo) |
completed | Sí | Analice result.images |
failed | Sí | Muestre error.message; cost es 0 (pre-cargo reembolsado) |
unknown | No | Reintentos cortos; si persiste, contacte a soporte con el id de la tarea |
Retry-After en 429. Las tareas se conservan ~3 días por defecto — guarde el id de la tarea si el cliente agota el tiempo de espera.
Ejemplo completado
{
"code": 200,
"data": {
"id": "task_01KZQE5CM0Y3KZ6M1N1BK619MX",
"status": "completed",
"progress": 100,
"created": 1786419262,
"completed": 1786419275,
"actual_time": 13,
"estimated_time": 100,
"cost": 0.08,
"credits_cost": 0.8,
"result": {
"images": [
{
"expires_at": 1786505675,
"url": [
"https://example.com/image/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.jpg"
],
"image_ids": [
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
]
}
]
}
}
}
Análisis de url e image_ids
result.images[]
├─ url[] ← authoritative display/download field (array)
├─ image_ids[] ← optional opaque IDs
└─ expires_at ← Unix seconds; multiply by 1000 for JS Date
- Use
url[]para la visualización; cuandon>1, recorra todas las entradas - Empareje por índice solo si
image_ids.length === url.length - Si faltan
image_ids, la visualización sigue siendo posible - Los enlaces duran 72 horas — descargue con prontitud; confíe también en
expires_at
Facturación
Precio base $0.08 por imagen (entregas exitosas):n | Base estimada |
|---|---|
| 1 | $0.08 |
| 4 | $0.32 |
| 8 | $0.64 |
| 12 | $0.96 |
- La UI previa al envío debe decir “estimación”; el USD final es
data.cost data.credits_costes la vista en créditos (actualmente ~ USD × 10)- Pre-cargo por la cantidad solicitada; liquidación por la cantidad exitosa (reembolsos parciales si hay fallo parcial)
- Fallo total:
cost=0, pre-cargo reembolsado - No construya claves de precio a partir de
resolution; este modelo tiene precio fijo por imagen
Webhook (opcional)
{
"webhook": "https://your-service.example.com/apimart"
}
- Proporcione una URL base; la plataforma llama a
{base}/callback - Debe ser pública y pasar las comprobaciones SSRF
- Si se define
webhook_secret, la firma eshex(HMAC-SHA256(secret, raw_body))sobre los bytes en bruto - El cuerpo del callback coincide con el
datade la consulta de tarea (sin envoltorio extra{code,data}) - Mantenga igualmente un sondeo de baja frecuencia como respaldo
Errores comunes
| HTTP | error.code | Causa | Acción |
|---|---|---|---|
| 400 | invalid_request | Prompt vacío / JSON no válido | Valide la entrada |
| 400 | invalid_n | n fuera de 1–12 | Limite la cantidad |
| 400 | invalid_size | Size no está en la lista blanca | Opciones fijas de selección |
| 400 | invalid_response_format | No es url | Corrija u omita |
| 400 | invalid_quality | Se envió el quality público | Use resolution |
| 400 | invalid_style | Se envió style | Elimine |
| 400 | invalid_image_input | Imágenes de referencia | Cambie de modelo |
| 400 | invalid_stream | stream=true | Elimine |
| 400 | invalid_idempotency_key | Key no válida | Use UUID |
| 401 | Fallo de autenticación | Key no válida | Corrija las credenciales del servidor |
| 402 | Pago requerido | Saldo bajo | Recargue |
| 409 | idempotency_* | Conflicto de idempotencia | Vea la tabla anterior |
| 429 | Límite de tasa | Demasiado rápido | Respete Retry-After |
| 5xx | Error del servidor | — | Conserve el Idempotency-Key; no rote a ciegas |
error.message en la UI. No exponga detalles internos de autenticación a los usuarios finales.
Diferencias respecto a 1.5 (resumen)
| Elemento | Grok Imagine 1.5 | 2.0 Ext |
|---|---|---|
| Modelo | grok-imagine-1.5-apimart, etc. | grok-imagine-2.0-ext |
| Imagen a imagen | Admitido (vea docs 1.5) | No admitido |
| Cantidad | Vea docs 1.5 | 1–12 |
| Campo de calidad | Vea docs 1.5 | resolution (quality); nunca quality público |
| Salida | Vea docs 1.5 | Solo URL |
| TTL de la URL | Vea docs 1.5 (a menudo 24h) | 72 horas |
| Precio unitario | Vea docs 1.5 | $0.08 / imagen |