What causes "model is required" in Wei-Shaw/sub2api?

Add an explicit "model" field (e.g. grok-2-image) to the request body or form

invalid_request_error

invalid_request_error

Error message

model is required

What it means

Thrown by AsyncImageHandler.validateRequest when the platform is Grok and the parsed media request (from Content-Type + body) has no model field (code=invalid_request_error). Grok image requests must name a model explicitly; there is no default.

Source

Thrown at backend/internal/handler/image_task_handler.go:197

	if err != nil {
		imageTaskError(c, err)
		return
	}
	c.Header("Cache-Control", "no-store")
	if task.Status == service.ImageTaskStatusProcessing {
		c.Header("Retry-After", "3")
	}
	c.JSON(http.StatusOK, task)
}

func (h *AsyncImageHandler) validateRequest(c *gin.Context, platform string, body []byte) error {
	if h.openAI == nil || h.openAI.gatewayService == nil {
		return nil
	}
	if platform == service.PlatformGrok {
		parsed := service.ParseGrokMediaRequest(c.GetHeader("Content-Type"), body)
		if strings.TrimSpace(parsed.Model) == "" {
			return errors.New("model is required")
		}
		return nil
	}
	parsed, err := h.openAI.gatewayService.ParseOpenAIImagesRequest(c, body)
	if err != nil {
		return err
	}
	if parsed.Stream {
		return errors.New("streaming image requests cannot be submitted as asynchronous tasks")
	}
	return nil
}

func (h *AsyncImageHandler) executeWithGateway(platform string, c *gin.Context) {
	if h.openAI == nil {
		imageTaskJSONError(c, http.StatusServiceUnavailable, "api_error", "image gateway is unavailable")
		return
	}

View on GitHub (pinned to 073e92d171)

Solutions

Add an explicit "model" field (e.g. grok-2-image) to the request body or form
Verify the Content-Type matches how the model field is being sent (JSON vs multipart)
Confirm the model name matches a Grok image model exposed by your deployment

Example fix

// before
{"prompt": "a cat"}
// after
{"model": "grok-2-image", "prompt": "a cat"}

Defensive patterns

Strategy: validation

Validate before calling

// TS: validate Grok image payloads before submit
function validateGrokImage(body: Record<string, unknown>) {
  if (!body.model || String(body.model).trim() === '') {
    throw new Error('model is required for Grok image tasks');
  }
}

Type guard

type GrokImageRequest = { model: string; prompt: string };
function isGrokImageRequest(v: unknown): v is GrokImageRequest {
  return typeof v === 'object' && v !== null && typeof (v as any).model === 'string' && (v as any).model.trim() !== '';
}

Prevention

Never rely on a default model for Grok image calls; set it explicitly
In multipart flows, double-check the model field name and Content-Type

When it happens

Trigger: Submitting an async Grok image task whose JSON body (or multipart form) omits "model", or contains a whitespace-only value.

Common situations: Porting OpenAI Images calls that relied on a default model; form-data submissions where the model field name is mistyped; agentic clients built for a provider that infers the model.

Related errors

AI-assisted analysis of Wei-Shaw/sub2api@073e92d171 (2026-08-15). Data as JSON: /api/errors/b06d738c37d8dc62. Report an issue: GitHub.