Cómo utilizar la API Grok Imagine Image 2.0 en EvoLink

Lo que construirás

Al final de la guía, su aplicación podrá:

1. crear una tarea de texto a imagen;
2. cambiar a la edición de referencias sin cambiar las ID del modelo;
3. utilizar referencias indexadas en un mensaje de varias imágenes;
4. realizar un seguimiento de una tarea asincrónica por ID;
5. aceptar una devolución de llamada de finalización de forma segura;
6. conservar los resultados antes de que caduquen sus URL de 24 horas;
7. conciliar el uso final y los reembolsos por tareas fallidas;
8. pasar a una ruta alternativa cuando la carga de trabajo o el resultado de la tarea lo requiera.

Antes de empezar

Paso 1: mantenga la clave API en el lado del servidor

Para una prueba de shell, establezca la clave en una variable de entorno:

export EVOLINK_API_KEY="your_api_key"

Paso 2: crea una tarea de texto a imagen

curl --request POST "https://api.evolink.ai/v1/images/generations" \
  --header "Authorization: Bearer ${EVOLINK_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Editorial product photograph of a teal glass perfume bottle on pale limestone, warm coastal morning light, restrained luxury art direction, no text or logos",
    "size": "1:1",
    "resolution": "1K",
    "quality": "medium",
    "n": 1
  }'

{
  "id": "task-unified-1757156493-imcg5zqt",
  "model": "grok-imagine-image-2.0",
  "object": "image.generation.task",
  "progress": 0,
  "status": "pending",
  "type": "image",
  "usage": {
    "billing_rule": "per_call",
    "credits_reserved": 3.06,
    "user_group": "default"
  }
}

El valor de la reserva anterior es un ejemplo de documentación, no una promesa de precio ni el cargo final. Utilice la página del modelo actual para conocer los precios en vivo y la respuesta de la tarea del terminal para el uso final.

Paso 3: consultar la tarea asincrónica

curl --request GET \
  "https://api.evolink.ai/v1/tasks/task-unified-1757156493-imcg5zqt" \
  --header "Authorization: Bearer ${EVOLINK_API_KEY}"

{
  "id": "task-unified-1757156493-imcg5zqt",
  "model": "grok-imagine-image-2.0",
  "object": "image.generation.task",
  "progress": 100,
  "status": "completed",
  "results": ["https://cdn.evolink.ai/images/generated-image.jpg"],
  "result_data": [
    {
      "url": "https://cdn.evolink.ai/images/generated-image.jpg",
      "mime_type": "image/jpeg"
    }
  ],
  "type": "image",
  "usage": {
    "credits_used": 3.06,
    "cost": {
      "credits": 3.06,
      "cny": 0.31,
      "usd": 0.05
    }
  }
}

Esos valores numéricos son valores de respuesta de ejemplo. Registre los valores devueltos por su propia tarea de terminal; No utilice este ejemplo para calcular la facturación del cliente.

Paso 4: agregar sondeo controlado

El sondeo debe detenerse en el estado de una terminal, retroceder entre solicitudes y aplicar un tiempo de espera de aplicación. El siguiente ejemplo de TypeScript del lado del servidor mantiene explícito el flujo de trabajo de la tarea:

type GrokTaskStatus = "processing" | "completed" | "failed";

type GrokTask = {
  id: string;
  status: GrokTaskStatus;
  progress: number;
  results?: string[];
  error?: {
    code: string;
    message: string;
    type: "task_error";
  };
};

const API_BASE_URL = "https://api.evolink.ai";

async function getTask(apiKey: string, taskId: string): Promise<GrokTask> {
  const response = await fetch(`${API_BASE_URL}/v1/tasks/${taskId}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
    cache: "no-store",
  });

  if (!response.ok) {
    throw new Error(`Task query failed with HTTP ${response.status}`);
  }

  return response.json() as Promise<GrokTask>;
}

async function waitForTask(
  apiKey: string,
  taskId: string,
  timeoutMs = 180_000,
): Promise<GrokTask> {
  const startedAt = Date.now();
  let intervalMs = 2_000;

  while (Date.now() - startedAt < timeoutMs) {
    const task = await getTask(apiKey, taskId);

    if (task.status === "completed" || task.status === "failed") {
      return task;
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs));
    intervalMs = Math.min(Math.round(intervalMs * 1.5), 10_000);
  }

  throw new Error("Grok Imagine Image 2.0 task timed out in the application");
}

Un tiempo de espera de aplicación no es prueba de que la tarea ascendente haya fallado. Antes de volver a intentar la generación, consulte la tarea original nuevamente o use una estrategia de idempotencia en su propia capa de trabajo. De lo contrario, un tiempo de espera del cliente puede crear tareas facturables duplicadas.

Paso 5: cambie a la edición de referencia única

curl --request POST "https://api.evolink.ai/v1/images/generations" \
  --header "Authorization: Bearer ${EVOLINK_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Move the chair into a quiet rain-soaked garden room. Preserve the chair shape, teal upholstery, camera angle, and scale. Change only the environment and reflected light.",
    "image_urls": [
      "https://example.com/chair.webp"
    ],
    "size": "4:3",
    "resolution": "1K",
    "quality": "medium",
    "n": 1
  }'

Su aplicación debe validar el recuento, el protocolo, el tipo de archivo y la accesibilidad del servidor antes de crear una tarea paga. Es posible que el servicio de generación aún no pueda acceder a una URL que funcione en un navegador conectado.

Paso 6: redactar con múltiples referencias

curl --request POST "https://api.evolink.ai/v1/images/generations" \
  --header "Authorization: Bearer ${EVOLINK_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "grok-imagine-image-2.0",
    "prompt": "Place the person from <IMAGE_0> in the architectural setting from <IMAGE_1>, carrying the blue sculptural bag from <IMAGE_2>. Preserve the outfit silhouette and match the late-afternoon direction of light.",
    "image_urls": [
      "https://example.com/person.webp",
      "https://example.com/location.webp",
      "https://example.com/bag.webp"
    ],
    "size": "3:4",
    "resolution": "2K",
    "quality": "medium",
    "n": 1
  }'

Almacene el orden exacto de la matriz con el mensaje. Si una interfaz de usuario permite a alguien reordenar las cargas, actualice la matriz y las etiquetas de índice juntas.

Paso 7: elija los parámetros por etapa del flujo de trabajo

Utilice una lista de solicitudes permitidas en lugar de pasar JSON de cliente arbitrario directamente a la API. Esto evita que campos no admitidos, lotes excesivos o URL de devolución de llamada interna lleguen a la ruta.

Paso 8: utilice devoluciones de llamada para completar la producción

{
  "model": "grok-imagine-image-2.0",
  "prompt": "A clean ecommerce product scene with soft daylight",
  "callback_url": "https://your-domain.com/webhooks/evolink/image-task"
}

El contrato actual dice que las devoluciones de llamada se envían después de la confirmación de facturación cuando una tarea se completa, falla o se cancela. EvoLink espera hasta 10 segundos y puede volver a intentar una devolución de llamada fallida tres veces después de 1, 2 y 4 segundos. Una respuesta 2xx marca la entrega exitosa.

Diseñe el receptor para que sea idempotente:

1. autenticar la solicitud utilizando el mecanismo que admite su cuenta EvoLink y la configuración del webhook;
2. validar el ID de la tarea y el modelo esperado;
3. insertar por ID de tarea en lugar de insertar un nuevo resultado en cada entrega;
4. devolver 2xx después de una persistencia duradera;
5. mover descargas lentas y revisar trabajos a una cola;
6. siga sondeando como ruta de recuperación cuando no se pueda confirmar la entrega del webhook.

La URL de devolución de llamada debe usar HTTPS y no puede apuntar a un host local, rangos de IP privados o una dirección de servicio interno.

Paso 9: guarde los resultados antes de que caduquen

Las URL de imágenes completadas permanecen disponibles durante 24 horas. Trátelos como URL de transferencia, no como almacenamiento permanente de aplicaciones.

Después de completar:

1. verificar que la tarea pertenece a la cuenta actual y al trabajo;
2. descargue todos los elementos en results o result_data;
3. validar el tipo de contenido y el tamaño del archivo;
4. almacene el archivo en su propio almacenamiento de objetos;
5. guarde la URL permanente y el hash de contenido;
6. registrar los parámetros de generación y revisar el estado;
7. aplicar su política de retención y eliminación a las entradas y salidas de referencia.

Paso 10: manejar fallas y facturación correctamente

Manejar errores HTTP a nivel de solicitud antes del sondeo

Algunas fallas ocurren antes de que se cree una tarea asincrónica. La referencia de API actual documenta estas respuestas a nivel de solicitud:

Paso 11: agregar enrutamiento alternativo

La integración debe separar el trabajo del producto del ID del modelo específico del proveedor:

type ImageRoute = "grok-imagine-image-2.0" | "gpt-image-2";

type ImageJob = {
  prompt: string;
  imageUrls: string[];
  requiresMask: boolean;
  requires4K: boolean;
};

function chooseImageRoute(job: ImageJob): ImageRoute {
  if (job.requiresMask || job.requires4K || job.imageUrls.length > 3) {
    return "gpt-image-2";
  }

  return "grok-imagine-image-2.0";
}

Este ejemplo es una política inicial a nivel de contrato, no una afirmación de que un modelo produce mejores imágenes. Agregue sus propios datos de aceptación, latencia, costo, moderación y observaciones de disponibilidad antes de enrutar tráfico significativo.

Lista de verificación de traspaso de producción

• [] Clave API almacenada en un administrador secreto del lado del servidor.
• [] La lista de cuerpos permitidos de la solicitud coincide con los documentos EvoLink actuales.
• El ID del modelo está centralizado en la configuración de la ruta.
• Las imágenes de referencia son públicas, validadas y limitadas a tres.
• [] Los índices de referencias múltiples coinciden con el orden de entrada persistente.
• [] El sondeo se detiene cuando se completa/falla y utiliza el retroceso.
• [] Los tiempos de espera de la aplicación no crean automáticamente tareas duplicadas.
• [] El procesamiento de devolución de llamada es idempotente y rápido.
• Los archivos de resultados se copian antes de que expiren las 24 horas.
• El uso final se almacena por separado de los créditos reservados.
• Se concilian los reembolsos de tareas fallidas.
• [] Los errores reintentables y no reintentables están separados.
• Existe una ruta alternativa probada para las capacidades requeridas o interrupciones.
• [] Los registros excluyen claves API y URL de referencia confidenciales.

Preguntas frecuentes

¿Qué punto final crea una tarea Grok Imagine Image 2.0?

¿Qué ID de modelo debo enviar?

¿Cómo paso de generación a edición?

¿Puedo enviar datos de imagen base64?

No. El contrato actual acepta URL HTTP o HTTPS de acceso público y no admite URL base64 o de datos.

¿Cómo consulto el resultado?

¿Debería realizar una encuesta o utilizar una devolución de llamada?

Utilice devoluciones de llamada para completar la producción normal y realizar sondeos como ruta de recuperación. Un prototipo simple del lado del servidor puede comenzar con un sondeo de retroceso.

¿Durante cuánto tiempo siguen siendo válidos los enlaces de imágenes completadas?

La documentación actual dice 24 horas. Copie los archivos completados al almacenamiento permanente de inmediato.

¿Se cobran las tareas fallidas?

¿Puedo solicitar 4K o Alta calidad?

No. Esta ruta actualmente admite 1K/2K y Bajo/Medio. Utilice una ruta verificada diferente cuando 4K o Alta sea un requisito estricto.

¿Dónde puedo comparar Grok con otra ruta de imágenes?

Fuentes

• EvoLink Grok Imagine Image 2.0 documentación API
• EvoLink documentación de API de estado de tarea
• Guía de flujo de trabajo y lanzamiento de Grok Imagine Image 2.0

Esta guía refleja el contrato EvoLink verificado el 12 de agosto de 2026. Vuelva a verificar la documentación de la API antes del envío, especialmente los campos del modelo, los límites de salida, el comportamiento de devolución de llamadas y los esquemas de respuesta a tareas.